Microsoft Teams

Microsoft Teams is a communication and collaboration platform designed to promote greater productivity through messaging and file-sharing tools.

Integrating Microsoft Teams with Cortex allows you to:

• Quickly find the relevant MS Teams channel to communicate with the right team, allowing for easier collaboration on projects and faster communication during an incident

  • MS Teams channels appear in the "Owners" block on entity details pages.

• Receive actionable notifications directly in MS Teams for Scorecard changes, upcoming Initiatives, weekly summaries of entity performance, and more

• Create Scorecards that enforce standards such as having an MS Teams channel set for projects

How to configure Microsoft Teams with Cortex

If you're using a self-managed Cortex instance, you'll need to follow a manual configuration process to use Cortex's app for Microsoft Teams. Follow the self-managed Teams guide here.

Step 1: Configure the integration in Cortex

1. In Cortex, navigate to the Microsoft Teams settings page.

   1. In Cortex, click your avatar in the lower left corner, then click Settings.

   2. Under "Integrations", click Microsoft Teams.

2. Click Add configuration.

3. In the side panel, click Connect account via Microsoft Teams OAuth. A popup window will appear.

4. In the pop-up window, follow the prompts to log in to your Microsoft account. The user configuring the integration must accept the permissions listed below:

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

After authenticating, you will be redirected to the Microsoft Teams integration settings page in Cortex. In the upper right corner of the page, click Test configuration to ensure Microsoft Teams was configured properly.

Step 2: Install the Cortex app for Teams through Microsoft AppSource

1. On the Microsoft Teams settings page in Cortex, click the Microsoft AppSource link.

2. In AppSource, click Get it now. You will be redirected to a page where you can choose whether to download a desktop app or use the web app.

Step 3: Configure a setup policy for Cortex in Teams

MS Teams admins can configure a setup policy for Cortex, can choose whether to automatically download the Cortex app into the personal Teams environments for users, and can choose to pin the app to make it more easily accessible.

If admins do not add a policy to install the Cortex app, then users will need to download the app during setup.

1. Navigate to the Teams admin center under Teams app > Setup policies.

2. Click Add to start configuring a setup policy for the Cortex app.

3. After configuring a policy, navigate to the Installed apps section. Add the Cortex app here.

   • This will automatically download the app in users' personal Teams environments.

   • MS Teams admins can also apply the policy to specific users in the Teams admin center under Users > Manage Users.

4. To pin the app, follow Microsoft's instructions on pinning apps.

Limitations

Cortex does not automatically discover MS Teams channels based on an entity tag, so you must define channels for each entity as described below.

How to connect Cortex entities to Microsoft Teams

In order to use this integration's functionality, your MS Teams channels need to be associated with entities in Cortex. Cortex does not automatically discover channels for MS Teams, so you must define them in the entity descriptor.

Editing the entity descriptor

To associate a Microsoft Teams channel with an entity, define a x-cortex-microsoft-teams block in an entity descriptor as shown in the example below.

Defining a Teams channel will provide direct access to the channel via the entity page in Cortex.

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

Using the Microsoft Teams integration

Viewing Microsoft Teams information across Cortex

• Entity details page: After MS Teams channels are defined in an entity's YAML, MS Teams channels will appear at the top of an entity's overview page in the MST channels block. Channels are also listed in the "Owners" page in an entity's sidebar. You can click any channel name to go directly to that channel in Microsoft Teams.

  
• You can write CQL queries and Scorecard rules based on Microsoft Teams channels. Learn more under Scorecards and CQL.

Managing Microsoft Teams notifications

After configuring the Microsoft Teams integration, you can choose whether to allow Microsoft Teams notifications for your workspace.

In Cortex under Settings > Notifications, an admin or a user with the Configure workspace notification settings permission can enable or disable the option to receive notifications via MS Teams for each type of notification. Users can also adjust their personal notification settings to control which notifications they receive via MS Teams.

Team, user, and entity MS Teams notifications

Notifications are user-based, team-based, or entity-based. DMs and channel notifications are sent from the Cortex app.

• User-based notifications are sent to users via a DM from the Cortex app.

• Team-based notifications are sent to the MS Teams channel associated with a team.

• Entity-based notifications are sent to the MS Teams channel associated with an entity.

Learn more about notifications in the Notifications docs.

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

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.

Still need help?​

The following options are available to get assistance from the Cortex Customer Engineering team:

• Email: [email protected], 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.