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 to1
Update the
user_menu_ordering
setting by appending themicrosoft
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.
Select the "+ New registration" button from the horizontal bar of options near the top of the page.
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.
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.
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.
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.
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.
Select the "+ New client secret" button.
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.
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.
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.
Select the "+ Add a permission" button.
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".
You will see a prompt of "What type of permissions does your application require?". Select "Delegated permissions" for this application.
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
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.
Updating the Elentra ME Settings File
Update your
settings-production.inc.php
andsettings-staging.inc.php
files to ensure they contain the following constants:
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"
Select the "Authorize Account" button next to the "OAuth Token" field.
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.
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 yourstaging
andproduction
users, making sure to replaceENTRADA_ABSOLUTE
with the absolute path to your Elentra installation.
Set the
active
flag to1
for themicrosoft:
artisan jobs in thecron
tableOptionally, you can also adjust the schedule. The default schedule runs once a day at 12:00 AM.
Troubleshooting Guide
Last updated