Microsoft Teams Integration

Feature Overview

New work was introduced in Elentra ME 1.22 to allow for integration with Microsoft Teams. This guide is intended to provide instructions on how to properly configure this integration.

Walkthrough

Enabling Microsoft Teams Integration in Elentra ME

Access Elentra ME's database (you can use a GUI client like Sequel Ace or any other preferred method). Make the following changes within the settings table:

• Set the value of the microsoft_teams_enabled setting to 1

• Update the user_menu_ordering setting by appending the microsoft menu entry to it (e.g. ...,gradingtasks,annualreport,privacy,notifications,microsoft)

Registering Elentra ME as an Azure Active Directory Application

In order for the Microsoft Teams integration to function, we need to add Elentra ME as a registered app through Microsoft's Azure Active Directory dashboard.

• From the Azure Active Directory dashboard, navigate to "App registrations" in the sidebar menu's "Manage" section.

App registrations

• Select the "+ New registration" button from the horizontal bar of options near the top of the page.

Add new registration

• This will display a "Register an application" dialog. Provide a title for the new application you are registering (e.g. "Elentra ME MS Teams Integration") and select the "Supported account types" that you want to grant access to.

Supported account types

• Enter a value for the "Redirect URI (optional)" field. This is the URI that the admin will return to after authenticating their account. The relative route in Elentra ME that handles authorization for Microsoft is /api/ms-graph-oauth.php, which can be appended to the rest of the address as seen in the screenshot below.

Redirect URI

• Once everything is correct, select the "Register" button. After a moment, you should see your newly registered application in the list of "Owned applications". Select the "Display name" link for the newly registered application to enter the management page for it.

Applications list

• On this management page for the registered application, you should see an expandable option titled "Essentials", that contains several "ID" fields. Copy and save the values for both the "Application (client) ID" and "Directory (tenant) ID" in a note where they can be retrieved later.

Essentials details

Configuring the Client Secret for the Application

Next, we need to generate a client secret.

• While still in the management page for the registered application, select the "Certificates & secrets" option under the "Manage" section in the sidebar menu.

Certificates & secrets

• Select the "+ New client secret" button.

New client secret

• Provide a "Description" label and choose a duration after which the secret will expire, using the "Expires" field. Once you are finished, select the "Add" button near the bottom of the screen.

New secret details

• Once you select the "Add" button, you should be presented immediately with some details regarding the client secret you have just created. Before leaving or refreshing this page, copy and save both the "Value" and "Secret ID" fields, as you will need them later.

Please Note: You will only be able to view these client secret values once, directly after creating them. If you forget to copy them down or misplace the details, you will need to generate a new client secret.

Copy the Value and Secret ID

Configuring API Permissions for the Application

• While still in the management page for the registered application, select the "API permissions" option under the "Manage" section in the sidebar menu.

API permissions

• Select the "+ Add a permission" button.

Add a permission

• On the next "Request API permissions" screen, you will be prompted to "Select an API". Under the "Commonly used Microsoft APIs" section, select "Microsoft Graph".

Microsoft Graph

• You will see a prompt of "What type of permissions does your application require?". Select "Delegated permissions" for this application.

Delegated permissions

• Use the "Select permissions" search field to filter the list of potential permissions, checking those that apply. When you have finished, select the "Add permissions" button. For the full list of permissions required for this integration, please refer to the MS_OAUTH_SCOPES setting as defined in Elentra ME's settings.inc.php file. At the time of writing, the required scopes are:

• offline_access

• User.ReadBasic.All

• Group.ReadWrite.All

• Team.Create

• Team.ReadBasic.All

• TeamMember.ReadWrite.All

Searching for required permissions

• Some scopes may require that you grant admin consent, which you can do by selecting the "Grant admin consent" button above the list of permissions. Doing so will display a modal dialog that asks for confirmation of this change.

Granting admin consent

Updating the Elentra ME Settings File

• Update your settings-production.inc.php and settings-staging.inc.php files to ensure they contain the following constants:

/*
 * Microsoft Teams/Azure Active Directory
 */
define("MS_SERVICE_TOKEN_ID", "microsoft_graph");
define("MS_AD_TENANT_ID", "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX");
define("MS_OAUTH_CLIENT_ID", "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX");
define("MS_OAUTH_CLIENT_SECRET", "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
define("MS_OAUTH_SCOPES", "offline_access,User.ReadBasic.All,Group.ReadWrite.All,Team.Create,Team.ReadBasic.All,TeamMember.ReadWrite.All");
define("MS_OAUTH_REDIRECT_URL", ENTRADA_URL."/api/ms-graph-oauth.php");

• Replace the value of MS_AD_TENANT_ID with the value from "Directory (tenant) ID" (see Registering Elentra ME as an Azure Active Directory Application section above)

• Replace the value of MS_OAUTH_CLIENT_ID with the value from "Application (client) ID" (Registering Elentra ME as an Azure Active Directory Application)

• Replace the value of MS_OAUTH_CLIENT_SECRET with the client secret's Value field (Configuring the Client Secret for the Application)

Authorizing the Microsoft Account

Please Note: Because Elentra's Microsoft Teams integration runs in the context of a single user, and due to the synching of Teams and Teams data being done by background cron tasks, you will need to use the Elentra user account with ID 1, set during installation as the default medtech:admin user account, to authorize the Microsoft account. This is a current limitation with the integration that may be addressed in the future.

• In the Elentra profile menu at the top of the page, select "Microsoft Account"

The profile menu's Microsoft Account

• Select the "Authorize Account" button next to the "OAuth Token" field.

Authorize Microsoft Account

Please Note: Selecting this button will redirect you to sign in to Microsoft, and then confirm the requested permissions.

• Below the "OAuth Token" field, select the appropriate "Outlook Time Zone" from the dropdown list of preconfigured time zones.

Selectin the Time Zone

Please Note: The time zone offset here must match the time zone configured Elentra ME to ensure that event start and end dates are set accordingly in Microsoft Outlook.

Configuring Automatic Synchronization

Elentra ME 1.22 introduced Laravel Task Scheduling. Cron jobs can now be controlled through the cron database table.

• Add the following job to your crontab by running crontab -e for both your staging and production users, making sure to replace ENTRADA_ABSOLUTE with the absolute path to your Elentra installation.

* * * * * php ENTRADA_ABSOLUTE/core/library/vendor/elentrapackages/elentra-1x-api/artisan schedule:run >> /dev/null 2>&1

• Set the active flag to 1 for the microsoft: artisan jobs in the cron table

• Optionally, you can also adjust the schedule. The default schedule runs once a day at 12:00 AM.

Troubleshooting Guide

Error	Troubleshooting Steps
When authorizing an Elentra account with Microsoft and attempting to set a Timezone, error is displayed: Unable to fetch available time zones from Outlook.	Ensure that the Elentra account has a Microsoft Object ID assigned in the Elentra profile. This can be obtained from the Azure Active Directory Portal in the Users page, and is labelled Object ID for each user in the Azure Active Directory Portal.
Team in Microsoft Team is not created for a configured Course. Error in api.log is displayed saying: Invalid access token for the Microsoft Graph API	Ensure that the Elentra account used to authorize with Microsoft is the MedTech user with User ID 1. This is the Elentra account whose generated Microsoft Access Token is used to synchronize data with Microsoft Teams by the background cron jobs.
Team in Microsoft Team is created for the Course and MedTech user used to configure the integration, but not enrolled learner	Ensure that the learner's Elentra account has a Microsoft Object ID assigned in the Elentra profile. This can be obtained from the Azure Active Directory Portal in the Users page, and is labelled Object ID for each user in the Azure Active Directory Portal.
Team in Microsoft Team is not created for the configured Courses and Events. No errors in any error logs are displayed.	Ensure that the four Microsoft records in the Elentra ME database cron table (i.e. those with artisan microsoft in the command) exist, and have active values set to 1. In addition, the schedule values can be adjusted to run when required. By default, the teams synchronization will run once a day at midnight. The format of the schedule is cron schedule expressions. To generate an expression, an online generator can be used, e.g. https://crontab.guru/
MS Teams link for a created Learning Event appears, but is not clickable to the Learner to join the Event	The MS Teams link for a configured Learning Event will appear as configurable, a set time before the Event begins. This time is configurable in the settings table in the Elentra ME database via the personal_meeting_window_minutes setting. The default value for this is 10 minutes.