Includes Google Productivity Tools (Gmail and Google Drive) and the Microsoft Productivity Tools (Outlook and One Drive) as Experience extensions.
- Google Cards
- Microsoft Cards
- Two Extension, One Repository
- Get the source
- Google Extension
- Microsoft Extension - build and upload
The Google extension includes two cards: Gmail and Google Drive.
The Gmail card in Ellucian Experience displays the 10 most recent inbox emails (both read and unread) from a user’s Gmail account. For each email, the card displays the sender’s name, subject, first line of the message, date received, and document icon (if an attachment exists). The user can click on any email in the Experience card to launch Gmail and open that email.
When a user first adds the Gmail card to their Experience Dashboard, they are prompted to sign in to grant permissions and authenticate their Google account. A user must select the 'View your email messages and settings' box on the Google permissions window to allow Elluciancloud access to display emails on the Gmail Experience card. If the box is not checked the Gmail Experience card will continue to display the 'Permissions Requested' message along with the Sign In button. Only one account may be authenticated to the Gmail card at a time. To switch to another account, the user can sign out and then sign in with the other account.
The list of emails in the card updates automatically every 60 seconds to display any new emails.
The Google Drive card in Ellucian Experience displays the 10 most recently modified documents from a user’s Google Drive account. For each document, the card displays the document title, modified date, name of the user who last modified the document, and an icon representing the document type. The user can click on any file name in the card to launch the Google Drive web application and open the selected file.
When a user first adds the Google Drive card to their Experience Dashboard, they are prompted to sign in to grant permissions and authenticate their Google account. A user must select the 'See and download all your Google Drive files' box on the Google permissions window to allow Elluciancloud access to display the files on the Google Drive Experience card. If the box is not checked the Google Drive Experience card will continue to display the 'Permissions Requested' message along with the Sign In button. Only one account may be authenticated to the Google Drive card at a time. To switch to another account, the user can sign out and then sign in with the other account.
The list of documents in the card updates automatically every 60 seconds to display any newly modified documents.
The Microsoft extension includes two cards: Outlook and OneDrive.
The Outlook card in Ellucian Experience displays the 10 most recent inbox emails (both read and unread) from a user’s Outlook account. For each email, the card displays the sender’s profile image, name, subject, first line of the message, date received, and document icon (if an attachment exists). The user can click on any email in the Experience card to launch Outlook and open that email.
When a user first adds the Outlook card to their Experience Dashboard, they are prompted to sign in to grant permissions and authenticate their Outlook account. Only one account may be authenticated to the Outlook card at a time. To switch to another account, the user can sign out and then sign in with the other account.
The list of emails in the card updates automatically every 60 seconds to display any new emails.
The Microsoft OneDrive card in Ellucian Experience displays the 10 most recently modified documents from a user’s OneDrive account. For each document, the card displays the document title, modified date, name of the user who last modified the document, and an icon representing the document type. The user can click on any file name in the card to launch the Microsoft OneDrive web application and open the selected file.
When a user first adds the Microsoft OneDrive card to their Experience Dashboard, they are prompted to sign in to grant permissions and authenticate their Microsoft account. Only one account may be authenticated to the Microsoft OneDrive card at a time. To switch to another account, the user can sign out and then sign in with the other account.
The list of documents in the card updates automatically every 60 seconds to display any newly modified documents.
To more easily share code between the two extensions, they have been combined into a single node package. This means there are departures from the standard Experience Extension npm scripts, extension.js, and webpack.config.js. There are separate Google and Microsoft versions of each.
For instance, during the development of the Google extension, use 'npm run google-start' in a terminal to run the webpack watch that builds as you make changes to the Google extension. Likewise, during the development of the Microsoft extensions, use 'npm run microsoft-start'.
To see all the npm run scripts, use 'npm run'
google-extension.js defines the Google Productivity Tools extension with its cards. microsoft-extension.js defines the Microsoft Productivity Tools extension with its cards.
Note each version of the webpack.config.js uses the appropriate extension.js. This provides separate entry points for each extension's cards.
Use your favorite Git tool to clone this repository.
- Obtain an upload token from Experience Setup and add that token to .env, as described in Build and upload an extension.
- Update publisher in
google-extension.js
. - Run 'npm install' to install all the dependencies.
- Run one of the deployment npm scripts, such as 'npm run google-watch-and-upload' (for development).
- Enable the extension and add it to an environment(s) in Experience Setup -> Extensions, using the procedure in Enable an extension in Experience environments.
The Google cards use a Google OAuth client ID to initiate an OAuth Authorization Code flow with PKCE. This is done using Google Identity's Google Sign-In for Websites see reference
The Google Client ID will be configured in Experience later.
- Log in to Google Cloud Platform console at https://console.cloud.google.com.
- Click on the project dropdown in the navbar and click "New Project", name appropriately, something like "Experience Test". Click "Create".
- Click "APIs & Services", then "OAuth consent screen"
- Select a User Type of "Internal", then click "Create."
- Enter an App name, such as "Experience". Select a required support email and if desired the App logo.
- Add an Authorized domain of "elluciancloud.com"
- Add the required Developer email address, then click "SAVE AND CONTINUE".
- In this step, you are defining what permissions this app is allowed to request. Click "ADD OR REMOVE SCOPES".
- In the dialog near the top, there is an infobox that has a link to Google API Library. Click this link and it will open a new tab.
- In the new tab, search for Gmail and click "Gmail API". When it opens click "Enable". Wait for it to complete, then close the tab.
- Once more click on the "Google API Library" link, which opens in a new tab.
- In the new tab search for Google Drive and click "Google Drive API". When it opens click "Enable". Wait for it to complete, then close the tab.
- Now to get the newly enabled API permissions to show in the list, refresh the browser. You may have to click "SAVE AND CONTINUE" again to get to the "ADD OR REMOVE SCOPES" button. Click this again as well.
- Now filter for gmail.readonly and select the check box next to it - Don't worry about the mislabeled API on this one. It shows Google Drive API even though this is for Gmail API.
- Clear the filter, and then filter for drive.readonly, then select the check box for this permission.
- Click "UPDATE", then the "SAVE AND CONTINUE" - OAuth consent is done.
- In the left nav select "Credentials." You need to create an OAuth 2.0 Client ID. Click "CREATE CREDENTIALS" at the top and pick OAuth client ID.
- Choose Application type of "Web application", then name it something like "Experience".
- Add a URI to the Authorized JavaScript origins. For Test use https://experience-test.elluciancloud.com. For Prod use https://experience.elluciancloud.com.
- Click "CREATE". You can copy the Client ID from here. Client Secret is not needed.
Configure the Google cards using the procedure in Set up an extension card in an environment. In the Configure step of the wizard, enter the Google OAuth client ID that you created in Google. A valid Google OAuth client ID will end with '.apps.googleusercontent.com'.
The Configure step values are shared by both Google Cards because it is an extension-level setting.
- Obtain an upload token from Experience Setup and add that token to .env, as described in Build and upload an extension.
optional .env variables.
OUTLOOK_MESSAGE_TEMPLATE_URL
can be used to customize the URL opened when you click on a mail message. Default is'https://outlook.office.com/mail/inbox/id/{id}'
OUTLOOK_USE_WEB_LINK
set to'true'
can be used to use the deep link webLink URL as sent by the Microsoft Graph API with the message. Default is false. - Update publisher in
microsoft-extension.js
. - Run 'npm install' to install all the dependencies.
- Run one of the deployment npm scripts, such as 'npm run microsoft-watch-and-upload' (for development).
- Enable the extension and add it to an environment(s) in Experience Setup -> Extensions, using the procedure in Enable an extension in Experience environments.
The Microsoft cards use an Azure AD Application ID to initiate an OAuth Authorization Code flow with PKCE. This is done using the Microsoft Authentication Library for JavaScript see reference.
The Microsoft Azure Redirect URL, Application ID, and Tenant ID will be configured in Experience later.
- Log in to the Azure portal https://portal.azure.com and select the Azure Active Directory Service.
- Click the "App Registrations" and create a new application in the tenant of your choice.
- Provide the name of your choice, eg. "Experience".
- Set the Redirect URI for the Single Page Application. Set this to the Ellucian Experience Dashboard URL from the About tab in Experience Setup.
- Click the application link you just created, and navigate to the Redirect URIs ‘spa’ link.
- Make sure it shows the Grant Type ‘Your Redirect URI is eligible for the Authorization Code Flow with PKCE’.
- The application has been created successfully.
-
You are now good to add permissions for the application. Open the API permissions for the selected application.
-
Click ‘Add a permission’.
-
Click Microsoft Graph and select the delegated permissions.
-
You would now be able to add permissions by selecting the permission and click Add Permission button. Add the following permissions:
- User.Read
- User.ReadBasic.All
- Mail.Read
- Mail.Read.Shared
- Files.Read
- Files.Read.All
-
Copy the ClientId and TenantId for the application, and configure them in the Experience OneDrive card configuration.
After setting the API permissions, here is how it will look:
Configure the Microsoft cards using the procedure in Set up an extension card in an environment. In the Configure step of the wizard, enter the Redirect URL exactly as it was entered in the Azure AD Application; the Azure AD Application ID; and Tenant ID.
The Configure step values are shared by both Microsoft Cards because it is an extension-level setting.
Copyright 2021–2022 Ellucian Company L.P. and its affiliates.