Microsoft Teams
Microsoft Teams is a communication and collaboration platform designed to promote greater productivity through its messaging and file-sharing tools.
By integrating Teams with Cortex, you can enable direct messaging to entity owners when there are Scorecard changes and when there are action items for upcoming Initiatives.
Setup and configuration
Getting started
You can use OAuth to connect to your Microsoft Teams instance from Teams settings in Cortex. Click Connect account via Microsoft Teams OAuth and follow the prompts in the modal to set up the integration.
If you do not see the settings page you're looking for, you likely don't have the proper permissions and need to contact your admin.
Once the integration is established, you'll see a message that says "Microsoft Teams OAuth is currently configured for your instance. Make sure that you've also installed Cortex's app for Teams through Microsoft AppSource."
Configuring Cortex's app for Microsoft Teams
Cortex's app for Microsoft Teams will enable Cortex to send notifications to users when scores in Scorecards change and with information about upcoming Initiatives. You can download Cortex's app for Teams through Microsoft AppSource.
Admins can create a setup policy from the Teams admin center under Teams app → Setup policies. Click Add to create and configure a setup policy for the Cortex app.
Once the policy is created, add the Cortex app under the Installed apps section. This will automatically download the app in users' personal Teams environments. Admins can also apply the policy to specific users by going to Users → Manage users, and selecting the created policy under the Policies tab.
If admins opt not to add a policy to install the Cortex app for everyone, each user will need to download the app during setup.
Admins can also pin the Cortex app to make it easily accessible to users.
Cortex Server users need to follow a manual configuration process to use Cortex's app for Microsoft Teams. Reach out to the support team for instructions.
API permissions
Cortex uses the Teams integration as an external identity provider to pull users into Cortex and to send notifications to channels (when enabled).
| Permission | Requirements | Description |
|---|---|---|
| Get organizations* | Organization.Read.All Directory.Read.All Organization.ReadWrite.All Directory.ReadWrite.All | Enables Cortex to get all organizations and fetch all repos for the import page |
| Get users* | User.Read.All User.ReadWrite.All Directory.Read.All Directory.ReadWrite.All | Pulls Teams users into Cortex |
| Get channels | ChannelSettings.Read.Group | Enables notifications |
| Get teams | Team.ReadBasic.All | Enables notifications to teams |
| Get team members | TeamMember.Read.Group | Enables Scorecard rule for Teams |
| Send messages | Teamwork.Migrate.All | Enables notifications for users/team channels |
*All listed permissions are required.
Registration
You can register Microsoft Teams channels by defining the following block in an entity descriptor. Defining a Teams channel will provide direct access to the channel via the entity page in Cortex.
Entity descriptor
x-cortex-microsoft-teams:
channels:
- name: team-engineering
teamName: engineering
description: This is a description for the engineering channel in Teams.
notificationsEnabled: true
| Field | Description | Required |
|---|---|---|
name | Microsoft Teams channel name (exact match) | ✓ |
teamName | Team name (exact match) | ✓ |
description | Description for the Teams channel | |
notificationsEnabled | Boolean to enable/disable notifications |
Expected results
Entity pages
Once Teams is connected via OAuth and channels are defined in an entity's YAML, you'll be able to find all channels associated with an entity on its details page. You can click any channel name to go directly to the channel in Microsoft Teams.
Scorecards and CQL
With the Microsoft Teams integration, you can create Scorecard rules and write CQL queries based on Microsoft Teams channels.
See more examples in the CQL Explorer in Cortex.
Check if Microsoft Teams channel is set
Checks if a given entity has a registered Teams channel in its entity descriptor.
Definition: microsoftTeams (==/!=) null
Example
For a Scorecard focused on team operations, you can make sure that each team entity has registered a Microsoft Teams channel:
microsoftTeams != null
Number of Microsoft Teams channels
Counts the number of Microsoft Teams channels for a given entity.
-
Channel name
-
Team name
Definition:
microsoftTeams.channels().length
Example
You can use this expression in the Query builder to identify teams missing a Microsoft Teams channel:
microsoftTeams.channels().length < 1
Total number of members across Microsoft Teams channels registered for the entity
Counts the total number of members across all Microsoft Teams channels registered for a given entity.
-
Channel name
-
Member name
-
Team name
Definition:
microsoftTeams.members().length
Example
For a Scorecard focused on team operations, you can verify that the Microsoft Teams channel has at least one member in it:
microsoftTeams.members().length > 0
Notifications
If a given entity has registered Teams channels, Cortex will automatically send notifications:
- When scores for an entity you own are re-evaluated due to cortex.yaml changes
- Information about recently created Initiatives you are included in
- Reminders a few days before an Initiative expires, including remaining action items
- When a scheduled rule is added to a Scorecard
- Reminders that a scheduled rule is going into effect 7 days and 1 day before
In practice, you'll also receive notifications from the Cortex bot in your Teams instance when there are changes to this Scorecard or any others you own.
Limitations
At this time, Cortex does not automatically discover channels based on an entity tag so channels must be defined for each entity.
Still need help?
The following are all the ways to get assistance from our customer engineering team. Please use the option that is best for your users:
- Email: help@cortex.io, or open a support ticket in the in app Resource Center
- Chat: Available in the Resource Center
- Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a
:ticket:reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your customer success manager.
Privacy Policy
We will retain basic Microsoft Teams metadata like user IDs for the period necessary to fulfill the purposes outlined in our Privacy Policy unless a longer retention period is required or permitted by law, or where the Customer Agreement requires or permits specific retention or deletion periods.