Skip to main content

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).

Get organizations*Organization.Read.All Directory.Read.All Organization.ReadWrite.All Directory.ReadWrite.AllEnables 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.AllPulls Teams users into Cortex
Get channelsChannelSettings.Read.GroupEnables notifications
Get teamsTeam.ReadBasic.AllEnables notifications to teams
Get team membersTeamMember.Read.GroupEnables Scorecard rule for Teams
Send messagesTeamwork.Migrate.AllEnables notifications for users/team channels

*All listed permissions are required.


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

- name: team-engineering
teamName: engineering
description: This is a description for the engineering channel in Teams.
notificationsEnabled: true
nameMicrosoft Teams channel name (exact match)true
teamNameTeam name (exact match)true
descriptionDescription for the Teams channelfalse
notificationsEnabledBoolean to enable/disable notificationsfalse

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.

  • Check if Microsoft Teams channel is set: Checks if a given entity has a registered Teams channel in its entity descriptor.
  • Number of Microsoft Teams channels: Counts the number of Microsoft Teams channels for a given entity.
  • 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.


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

Real-world examples

For a Scorecard focused on team operations, you can make sure that each team entity has registered a Microsoft Teams channel using:

microsoftTeams != null

You can also verify that the Microsoft Teams channel has at least one member in it with:

microsoftTeams.members().length > 0

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.


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:, 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.