Connecting to Microsoft Exchange

This article covers how to connect Openprise to Microsoft Exchange calendar when setting up a data source. You can learn more about Data Sources here. 

Microsoft Exchange: Service Account Set-up

Before configuring your Microsoft Exchange data source you must first create an app via the Microsoft Entra Admin Center. You will need to have access to a user account, which has Global Administrator privileges. Only one application needs to be configured to access data of all users within your organization. 

Determine if a user has Global Administrator privileges

1. Log into the Microsoft 365 Admin center using the following link: https://admin.cloud.microsoft/#/homepage.
2. Navigate to Users > Active Users
3. Select the Display/User Name of the account that you are interested in. Use the user pop-up to see what role they have been assigned 

Create a Global Administrator user

1. Select “Manage Roles” under the desired user profile and then specify “Global Administrator”

Create an Exchange Application in Microsoft's Entra Admin Center:

You will need to create a Microsoft Exchange Application prior to configuring your data source. Use the following Microsoft reference guides: 

• https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=certificate
• https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-configure-app-access-web-apis

Setup Steps:

1. Sign in-to the Microsoft Entra Admin center as a Global Administrator.
2. If you have access to multiple tenants, use the Settings icon in the top menu to switch to the desired tenant.
3. Navigate to Identity > Applications > App Registrations > New Registration

4. Enter a name for the application (i.e. “OP Exchange”) and select “Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant)” when asked to specify who can use the application. You do not need to enter a redirect URI.
5. Click “Register” to finish the registration process.
6. Return to Identity > Applications > App Registrations tab. You should now see the new application under “Owned Applications” or “All Applications”.

7. Select the application created and navigate to the “Certificates & secrets” tab
8. Select “Client secrets” > “New client secret”. Add an optional description to your client secret if desired.
9. Select an expiration for your secret and note when it expires. Once the secret expires, you will need to generate a new one for the application using this same process, then re-enter the new credentials for Exchange connector via the Openprise platform. Recommended expiration time is 12 months or less.
10. Record the client secret “Value”. You will not be able to access this value again once you leave the creation page.
11. Navigate to the API Permissions tab and select “Add a permission”, then select Microsoft Graph from the pop-up. 
12. Select “Application permissions”, then find and check the following 4 permissions: 
    1. Calendars.Read
    2. Contacts.Read
    3. Mail.Read
    4. User.Read.All

13. Navigate to the App roles tab to create the required App roles for the application. You will need to create 4 app roles, one for each of the permissions specified in the previous step. The parameters for each should be as followed:
    1. Display Name: Calendars.Read
       • Allowed Member Types: Both (Users/Groups + Applications)
       • Value: Calendars.Read
       • Description: Read Calendars. Ensure that the checkbox labeled “Do you want to enable this app role?” is selected.
       • Select Apply
    2. Display Name: Contacts.Read
       • Allowed Member Types: Both (Users/Groups + Applications)
       • Value: Contacts.Read
       • Description: Read Contacts. Ensure that the checkbox labeled “Do you want to enable this app role?” is selected.
       • Select Apply
    3. Display Name: Mail.Read
       1. Allowed Member Types: Both (Users/Groups + Applications)
       2. Value: Mail.Read
       3. Description: Read Mail. Ensure that the checkbox labeled “Do you want to enable this app role?” is selected.
       4. Select Apply
    4. Display Name: Users.Read.All
       1. Allowed Member Types: Both (Users/Groups + Applications)
       2. Value: Users.Read.All
       3. Description: Read All Users. Ensure that the checkbox labeled “Do you want to enable this app role?” is selected.
       4. Select Apply

14. Once you have created these 4 app roles, in the app registration screen, select Manage > Owners > Add Owners and select the user under whose account you created the app. 
15. Return to the API Permissions tab. Select Add Permissions > My API’s (top of the pop-up) > Select the application you created/registered in step 5.
16. Select each of the permissions that appear under Application Permissions and then select “Add Permissions”.

NOTE: If you see any permissions of type “Delegated” under the Microsoft Graph Permissions list, select the 3 dots to the right and select “Remove permission”.

17. Navigate back to the API Permissions tab and Select “Grant admin consent for [TenantName]”. Ensure that all of the permissions have a consent status of “Granted”. There should be 8 in total.
18. Navigate to the “Overview” tab and take note of the Application (client) ID and Directory (tenant) ID. You will need the clientID, tenantID and client secret to authenticate this application via the Openprise platform.

Exchange Calendar Field Information

Use the following Microsoft reference guides to learn more about Events and Attendees:

• Microsoft Events: https://learn.microsoft.com/en-us/graph/api/resources/event?view=graph-rest-1.0
• Microsoft Attendees: https://learn.microsoft.com/en-us/graph/api/resources/attendee?view=graph-rest-1.0

Field Definitions:

• attendee_emailAddress: Email address of an event attendee. Each event is divided into separate records so each record corresponds to an event attendee
• attendee_response: response type for a given attendee/record, possible values are [“none”, “organizer”, “tentativelyAccepted”, “accepted”, “declined”, “notResponded”]
• attendee_response_time: date and time when attendee response was received, default value if no response has been given is “0001-01-01T00:00:00Z”, UTC/GMT format
• attendee_type: attendee type, possible values are [“required”, “optional”, “resource”]
• attendeeName: name of the attendee for a given record, if not in the user’s contacts/Exchange organization this value may be the same as attendee_emailAddress
• bodyPreview: preview of the message associated with the event
• categories: categories associated with the event, formatted in multi-text and unique to the specific user’s calendar from which the record is derived
• createdDateTime: date and time of event creation, UTC/GMT format
• endDateTime: date time representation of when the event is scheduled to end, UTC/GMT format
• event_id: id of the event; this is NOT a unique identifier as we are dividing events into separate records depending on the number of associated attendees
• hasAttachments: boolean value, true if the event has attachments
• hideAttendees: boolean value with default of false - when true, attendees will only see themselves in the meeting request
• iCalUId: id of event that is the same across user calendars
• importance: importance of the event, possible values are [“high”, “normal” and “low”]
• isAllDay: boolean value, true if the event is all day
• isCancelled: boolean value, true if the event is canceled
• isDraft: boolean value, true if the event is marked as a draft
• isOnlineMeeting: boolean value, true if the event has online meeting information
• isReminderOn: boolean value, true if an alert is set to remind the user of the event
• lastModifiedDateTime: date time representing the last time the event was modified, UTC/GMT format
• onlineMeetingProvider: represents the online meeting service provider, possible values are [“unknown”, “teamsForBusiness”, “skypeForBusiness”, “skypeForConsumer”], default value is “unknown”
• organizer_emailAddress: email address of the person who created the event
• organizer_Name: name of the person who created the event
• reminderMinutesBeforeStart: number of minutes before the event start time that a reminder is sent
• responseRequested: boolean value, represents whether the event organizer would like an invitee to send a response to the event, default true
• responseStatus_response: response type, possible values are [“none”, “organizer” “tentativelyAccepted”, “accepted”, “declined”, “notResponded”]
  • none - from organizer’s perspective, used when the status of the event is reported to the organizer of the meeting
  • notResponded - from attendees perspective, indicates the attendee has not responded to the meeting
• responseStatus_time: date and time when the response was returned, UTC/GMT format
• sensitivity: corresponds to the sensitivity of the event - Openprise will only ever fetch events with a sensitivity label of”normal”, other possible values include “personal”, “private” and “confidential”
• showAs: status to show, possible values are [“free”, “tentative”, “busy”, “oof” “workingElsewhere”, “unknown”]
• startDateTime: date time representing when the event is starting, UTC/GMT format
• Subject: subject/title of the event

Data Source Configuration

When creating a new data source, select Microsoft Exchange from the source technology and data format picklist.

1. Select the Add Account Information button to link your Microsoft Exchange account to Openprise
2. Click on the Add Account button to sign into your Microsoft Exchange account using your credentials
3. Select from an existing account if you've already linked your Microsoft Exchange account to Openprise

If you selected the Add Account button, you will need to include the clientID, clientSecret, tenantID, and accountUser from your Microsoft Exchange account. 

Select Calendar from your Microsoft Exchange account as the directory or entity. 

Data Source containing Exchange email addresses - You will need to import a separate data source containing Microsoft Exchange email addresses prior to configuring your Microsoft Exchange data source. Create and import the data source as a Google Sheet. Select the data source from the picklist.  

• Data Inclusion Filter - create an optional filter to import specific data from the email address data source
• NOTE: Calendar entries from the list of user's primary calendar with a sensitivity of "normal" will be imported.  

Select the attribute containing Microsoft Exchange email address from the data source. 

Advanced Configurations - Events will only be imported if they fall within the data range configured in Advanced Configurations. The default range is 30 days in the past and 30 days in the future, relative to the time of import. 

NOTE:

• Each calendar entry is divided into separate records based on the number of attendees to the event. This means that a particular event could appear multiple times in a given import, depending on the number of attendees associated with the event.
• If you are pulling in User A’s and User B’s calendar event entries and these users are attendees to the same event “Random”, the event data will be imported for both User A and User B. There could be duplicate records. The number of duplicate entries depends on the number of users specified for import who are attendees to the given “Random” event, and have added the event to their primary calendars.