Microsoft Outlook Integration with Simpplr

Table of Contents

Overview

Security

Enabling Outlook Calendar

User Connection

Calendar Visibility and Expected Functionality

To Consider when Sharing Calendars

Multi-Domain Calendar Support

Overview

With the Microsoft Outlook calendar integration, Site managers will be able to integrate shared calendars into tiles on their Simpplr sites to bring wider visibility into company events, while End users will be able to integrate their personal calendars for easy visibility. 

Note:

The user who enables the integration at the application level first must be an Application manager as well as the Microsoft/Outlook Global Admin user, as consent from the admin is needed to complete the integration. Without this connection, other users in the organization won't be able to connect their profiles. No other account will work when establishing the initial connection. This is a requirement from Microsoft, and cannot be changed. For more on Microsoft's security requirements and permissions for 3rd party integrations, check out this article. 

The account you use to establish the connection should have "Email" listed in the Azure properties as well.

Security

Scope of Data accessed

To access data, Simpplr uses "delegated access" (Delegated access = “Access on behalf of a user”).

Application access is used only to create the custom app with no user data access.

Simpplr does not necessarily require the Global Admin role to connect and enable the integration. Any user can set up and configure the integration by adding Domains at the app level. If they are not a Global admin they can request for permissions on the consent screen itself.

A Global Admin is needed to log into the admin center and provide consent for custom app permissions that’ll be registered in your MS tenant.

The requested permission scopes might seem alarming as they mention "all users."

The Microsoft-generated consent screen should ideally clarify that the permissions are granted “on behalf of the signed-in user,” but this phrasing is missing.

OAuth secures authentication and authorization

• Simpplr accesses Outlook as the user, never as a Global Administrator.

• Users need to explicitly permit Simpplr to access Outlook.

• The Global Administrator (GA) must approve this user request by granting consent.

  • This consent is done once and applies to all users, with the GA choosing to “consent on behalf of the organization.”

• All actions performed in Outlook are logged by Microsoft as actions taken by Simpplr on behalf of that specific end user.

Permission set from production

Maintain access to data you have given it access to Allows the app to see and update the data you gave it access to, even when you are not currently using the app. This does not give the app any additional permissions. Read your calendars Allows the app to read events in user(that specific end-user) calendars. Sign in and read your profile Allows users to sign in to the app, and allows the app to read the profile and basic company information of the specific signed-in user. Read user and shared calendars Allows the app to read events in all calendars that the user can access, including delegate and shared calendars.

Enabling Outlook Calendar

To get started:

1. The Microsoft Global Admin user (who must also have App manager permissions) can head to Manage > Application > Integrations > Domains.
2. Find Microsoft from the options and add any applicable domains your organization uses. You can add up to 10. More on multi-domain support below. At least one domain must be added to enable the integration for other users.
3. Choose the applications you'll be using in conjunction with Simpplr. Currently you can choose Outlook, OneDrive and SharePoint. When finished, click Add domain. Repeat these steps for each domain you want to add. 
4. Now head to Calendar integration and choose Microsoft Outlook Calendar. Then click Save.

Once enabled, all users will now have the option to connect their accounts.

Disclaimer on images from Simpplr appearing in your Outlook inbox:

Note that customers in the past have reported issues with images in emails from Simpplr not appearing in Outlook inboxes. While we cannot guarantee a solution to this problem, and this issue stems from many different org/domain setups on the customer's Outlook side, we have seen success by passing along this help article from Microsoft on blocking/unblocking automatic image downloads in Outlook.

User Connection

Like other integrations, in order to utilize the Outlook Calendar features, users will need to connect their accounts in their profile settings. 

• Users connection is successful only when the domain used is one of the listed domains at app level.
• If a user attempts to connect a calendar that's not added as part of the Domains list in Manage > Application, they'll receive an error suggesting the domain is not supported.

To connect your profile:

1. Head to Profile & settings from your user menu.
2. Click Edit profile & settings > External apps. Choose Connect account  n the Microsoft Outlook Calendar field.

3. Accept the permissions being requested by Simpplr in order to use the integration.

   
   

Outlook Events Listing

Once user level connection is complete, users will be able to view the Outlook calendar events in a separate tab under Events listing.

Adding Outlook Calendar Tiles

Calendar tiles are a great way for the users to have a quick view of their upcoming meetings included on their dashboard. Once Outlook calendar is enabled at app level and user connection is also done, a new option of adding Outlook calendar can be used to add the tiles on home/site dashboard. Based on the app management governance settings, App managers/Site managers/End users can add tiles to their dashboard.

• If the Home dashboard is app manager controlled, only app managers can add Outlook calendar tiles to home dashboard for all users.
• If the Home dashboard is user-controlled, end users can also add calendar tiles to their dashboard.
• Site managers/owners can always add calendar tiles to the Site dashboard for the sites they manage.

Calendar Visibility and Expected Functionality

Shared calendars: When adding a shared calendar to your Simpplr tiles, it should be visible to all users whom it's been individually shared with, unless the calendar got renamed after adding as a tile, or someone's access to it was removed via Microsoft. Note if a calendar is shared across multiple domains, it still will not be visible to users in Simpplr if they're connected to a different domain than that of the calendar owner/source domain.

Personal calendars: The events from a personal calendar, if added as a tile, would be visible to only those who have access from within Microsoft. 

Public calendars and corporate calendars: These are not supported by this integration. 

Shared mailbox: As of the 24.02 release, users are able to create a calendar display from a shared mailbox in Outlook. This will allow Simpplr tiles that display org-wide calendars based on shared mailboxes.

Note that with shared mailboxes, the email address (labeled as Email ID) of the shared mailbox is required as an input when adding the tile, as shown in the image above. This will prompt Simpplr to fetch any shared mailboxes tied to that email address.

Similar to any other calendar tile, if you select to add the shared mailbox calendar to all users' home dashboards, users who are not part of that shared mailbox will see the tile, but not the calendar events. Instead, they will see a message, "You do not have access to this calendar". This may result in a poor user experience, so best practice is to ensure the shared mailbox consists of all users if you're planning to add that calendar tile to everyone's home dashboard.

If a specific user is removed from a shared mailbox, it can take up to one hour for Microsoft to update this in their API response. Therefore, the user could still view events in the Outlook tile on the intranet. After an hour, they will see the message, "You do not have access to this calendar".

To Consider when Sharing Outlook Calendars...

When it comes to sharing calendars with users, Outlook's API prohibits sharing in Simpplr unless you share the calendar on an individual level with each user you want to give access to. This must be done within Outlook, and the user(s) you share with must accept the sharing invite via their email in order to see the calendar events in the Simpplr tile. 

To share a calendar so users can see it in Simpplr:

1. From your Outlook, head to the calendar in question. Then click the more options ellipsis to open the Sharing & permissions menu.
   
2. Type in the email(s) of the user(s) you want to share the calendar with, assign the appropriate permission for the calendar, then click Share.
   
3. The user(s) will receive an email from you inviting them to accept the calendar sharing invite. They will need to click Accept in that email in order to view the events within their Simpplr tile.

Multi-Domain Calendar Support

If a calendar is shared across multiple domains, it will not be visible to users in Simpplr if they're connected to a different domain than that of the calendar owner/source domain.

When a user from one domain, [e-mail], shares calendar to user from another domain, [e-mail], then the calendars returned from Graph API for Jane.Doe for  will have the result of "owner = null". In Outlook calendar, Simpplr does not have a unique calendar ID for a shared calendar across users, therefore we are relying on the owner name and calendar name for shared calendars. Since in cross domain calendars, we get "owner = null" from the API, our shared calendar logic will not be supported in shared calendars across domains.