Integrate Microsoft Outlook

Deploy the Microsoft Outlook integration to schedule events and office hours, edit events and office hours, and receive a notification an hour before an event’s start time.

Note:

This integration template is in Preview and marked as Preview in the list of available templates that are shown in the product when adding a new integration. While in Preview, there is no commitment to support, and support is provided by the developer on a best-effort basis. Preview integration templates are shared for the purpose of testing and validation. We do not advise deploying them in production environments. For more information, see Maintenance statement for Microapps integration templates.

For comprehensive details of the out-of-the-box microapp for Microsoft Outlook, see Use Microsoft Outlook microapps.

Review prerequisites

After you set up this integration with Microsoft Outlook, you will need these artifacts to add the integration in Citrix Workspace Microapps:

  • BASE URL: https://graph.microsoft.com/
  • AUTHORIZATION URL: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
  • TOKEN URL: https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token
  • CLIENT ID: The client ID is the string representing client registration information unique to the authorization server.
  • SECRET: The client secret is a unique string issued when setting up the target application integration.

Note:

It is recommended that you always use OAuth 2.0 as your service authentication method where available. OAuth 2.0 ensures that your integration meets the maximum security compliance with your configured microapp.

Configure Citrix Gateway to support single sign-on for Microsoft Outlook so that once users log in they are automatically logged in again without having to enter their credentials a second time. For more information about configuring SSO, see Citrix Gateway Service «https://docs.citrix.com/en-us/citrix-gateway-service/>.

The integration requires regular access to your Microsoft Outlook instance, so we recommend creating a dedicated user account. You can view the permission/privileges at https://docs.microsoft.com/en-us/graph/permissions-reference. This account must have the following permissions:

  • Permissions required for Service Account: Full administrator privileges

The number of API requests that can be made to specific resources is limited, we therefore recommend the following:

Create a new service account

Sign in here: https://account.microsoft.com/.

Configure OAuth server

Configure the OAuth server to read data through the Microsoft Outlook integration.

  1. Log in with your service account to: https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps
  2. Select New registration.
  3. For Supported account types, select Accounts in any organizational directory (Any Azure AD directory - Multitenant).
  4. Complete the required fields and enter the following authorized redirect URLs for this integration in the Redirect URL field: https://{yourmicroappserverurl}/admin/api/gwsc/auth/serverContext
  5. Click on Register.
  6. Copy and save the Application (client) ID and Directory (tenant) ID shown on the screen. You use these details for Service Authentication while configuring the integration.
  7. Click on View Permissions under Call API’s and select Add a permission and choose Microsoft Graph tile.
  8. Select Application permissions tile and add these listed scopes: **User.Read.All Calendars.Read**
  9. Select Grant admin consent for Citrix Systems and select Yes.
  10. Select Certificates & secrets from left panel and select New client secret and choose the expiration validity as never and click on add.
  11. Copy and save the Value from the client secrets.

Configure OAuth client

Configure the OAuth client to write back data through the Microsoft Outlook integration.

  1. Log in with your service account to: https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps
  2. Select New registration.
  3. For Supported account types, select Accounts in any organizational directory (Any Azure AD directory - Multitenant).
  4. Complete the required fields and enter the following authorized redirect URLs for this integration in the Redirect URL field: https://{yourmicroappserverurl}/app/api/auth/serviceAction/callback
  5. Click on Register
  6. Copy and save the Application (client) ID and Directory (tenant) ID shown on the screen. You use these details for Service Authentication while configuring the integration.
  7. Click on View Permissions under Call API’s and select Add a permission and choose Microsoft Graph tile.
  8. Select Delegated permissions tile and add these listed scopes: **Calendars.ReadWrite**
  9. Select Grant admin consent for Citrix Systems and select Yes.
  10. Select Certificates & secrets from left panel and select New client secret and choose the expiration validity as never and click on add.
  11. Copy and save the Value from the client secrets.

Add the integration to Citrix Workspace Microapps

Add the Microsoft Outlook integration to Citrix Workspace Microapps to connect to your application. The authentication options are preselected. Ensure that these options are selected as you complete the process. This delivers out-of-the-box microapps with pre-configured notifications and actions which are ready to use within your Workspace.

Follow these steps:

  1. From the Microapp Integrations page, select Add New Integration, and Add a new integration from Citrix-provided templates.
  2. Choose the Microsoft Outlook tile.
  3. Enter an Integration name for the integration.
  4. Enter Connector parameters.

    • Enter the instance Base URL: https://graph.microsoft.com/
    • Select an Icon for the integration from the Icon Library, or leave this as the default icon.
  5. Under Service authentication, select OAuth 2.0 from the Authentication method menu and complete the authentication details. The authentication options are preselected. Ensure that these options are selected as you complete the process. Use the OAuth 2.0 security protocol to generate request/authorization tokens for delegated access. It is recommended that you always use OAuth 2.0 as your service authentication method where available. OAuth 2.0 ensures that your integration meets the maximum security compliance with your configured microapp.

    1. Select Client Credentials from the Grant type menu.
    2. Select Request body from the Token authorization menu.
    3. The Token URL is prefilled: https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token
    4. Ensure the following is entered for Scope: .default offline_access
    5. Enter your Client ID. The client ID is the string representing client registration information unique to the authorization server. You collect this and the secret when you configure the OAuth server. You need to add the Callback URL you see on the integration configuration page.
    6. Enter your Client secret. The client secret is a unique string issued when setting up the target application integration.
  6. Under Service Action Authentication, enable the Use Separate User Authentication in Actions toggle. Service action authentication authenticates at the service action level. The authentication options are preselected. Ensure that these options are selected as you complete the process.

    1. Select OAuth 2.0 from the Authentication method menu and complete the authentication details.
    2. Select Request body from the Token authorization menu.
    3. Select Authorization code from the Grant type menu. This grants a temporary code that the client exchanges for an access token. The code is obtained from the authorization server where you can see the information the client is requesting. Only this grant type enables secure user impersonation. This will display the Callback URL, which you use when registering your application.
    4. The Authorization URL is prefilled: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
    5. The Token URL is prefilled: https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token
    6. Ensure the following is entered for Scope: .default offline_access
    7. Enter your Client ID. The client ID is the string representing client registration information unique to the authorization server. You collect this and the secret when you configure the OAuth client. You need to add the Callback URL you see on the integration configuration page.
    8. Enter your Client secret. The client secret is a unique string issued when setting up the target application integration.
  7. Enable the Enable request rate limiting toggle. Enter 60 for Number of requests and 1 second for Time interval.
  8. (Optional) Enable Logging toggle to keep 24 hours of logging for support purposes.
  9. Select Save to proceed.
  10. Under OAuth Authorization, select Authorize to log in with your service account. A pop-up appears with a Microsoft login screen.
    1. Enter your Service Account username and password and select Sign in.

The Microapp Integrations page opens with your added integration and its microapps. From here you can add another integration, continue setting up your out-of-the-box microapps, or create a new microapp for this integration.

You are now ready to set and run your first data synchronization. As a large quantity of data can be pulled from your integrated application to the Microapps platform, we recommend you use the Table page to filter entities for your first data synchronization to speed up synchronization. For more information, see Verify needed entities. For complete information about synchronization rules, synchronization that does not meet its schedule and veto rules, see Synchronize data.

Note:

The Citrix Microsoft Outlook integration uses Data Update After Action to pull in the most recent data for the logged in user via the Refresh Table button in the My Calendar service action. We recommend to use this approach as is. Please utilize the default full synchronization once every week for retaining an optimum amount of data for the user. Additionally, the integration doesn’t support incremental synchronization and relies solely on Data Update After Action to pull in the most recent data. It is recommended to set the “Full Synchronization” interval as Weekly to remove the cancelled or deleted events from Microapps platform and subsequently from the user’s calendar.

Refresh button is used to sync cache with the most recent data, in lieu of full/incremental synchronization. Since this integration doesn’t rely on full/incremental sync for latest data pull, pagination is not needed nor implemented. This also helps limit api calls.

For more details of API endpoints and table entities, see MS Outlook connector specifications.

Note:

Calendarview data endpoint is hardcoded with past start_date_time and end_date_time, since they are mandatory. However, the user will view the most recent data in their microapps using the Refresh button concept.

Use Microsoft Outlook microapps

Existing application integrations come with out-of-the-box microapps. Start with these microapps and customize them for your needs.

Note:

As the currently available 40 time zones are hardcoded in the Create Event, My Office Hours and My Calendar microapps, adding any other time zone would require the admin to add them manually.

Create Event: Microapp is used to schedule an Event/Meeting as per the user preference.

Notification or Page Use-case workflows
Create Event page Provides a form to schedule an event with the following details according to user preference: Event Title, Start Date/Time, End Date/Time, TimeZone, Recurrence (once, daily, weekly, monthly), Location, Description and Attendees or Guests for the meeting.

My Calendar: Microapp is used to view and edit upcoming Events/Meetings.

Note:

The Event Reminder notifications are triggered only to the event organizer one hour before event start_date_time. This notification only gets triggered for the events which are in the Microapp server cache at any given point. To ensure timely notifications, we recommend using the Refresh Table button on a frequent basis and also running the weekly Full sync as is, to avoid any incorrect/deleted event notifications.

Notification or Page Use-case workflows
Event Reminder notification Event owner receives a notification before an hour of the event start time.
Upcoming Event Detail page Provides a read only view of an event with details, button to join meeting and edit button for event owner only.
Upcoming Events page Allows users to search for events.
Event Detail page Provides a read only view of event with details. Edit option is available for the event owner.
Edit Event page Provides a form for editing an event.

My Office Hours: Microapp is used to create, view, and edit virtual office hours.

Notification or Page Use-case workflows
Virtual Office Hours page Allows users to view the office hours.
Create Office Hours page Provides a form to schedule virtual office hours with the following details according to user preference: Start Date/Time, End Date/Time, TimeZone, Recurrence (daily, weekly, monthly), Description for the office hours.
Edit Office Hours page Provides a form for editing office hours.
Integrate Microsoft Outlook