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.

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.

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

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: [e-mail], 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.