# Microsoft Teams [Microsoft Teams](https://www.microsoft.com/en-us/microsoft-teams/group-chat-software) 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](https://docs.cortex.io/ingesting-data-into-cortex/entities/details). * Receive actionable [notifications](#managing-microsoft-teams-notifications) directly in MS Teams for Scorecard changes, upcoming Initiatives, weekly summaries of entity performance, and more * Create [Scorecards](https://docs.cortex.io/standardize/scorecards) that enforce standards such as having an MS Teams channel set for projects ## How to configure Microsoft Teams with Cortex {% hint style="warning" %} This page describes how to integrate Microsoft Teams with Cortex cloud. 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](https://docs.cortex.io/self-managed/features/integrations/ms-teams). {% endhint %} ### Step 1: Configure the integration in Cortex 1. In Cortex, navigate to the [Microsoft Teams settings page](https://app.getcortexapp.com/admin/integrations/microsoftteams). 1. Click **Integrations** from the main nav. Search for and select **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 Application-type permissions listed below: | Permission | Requirements | Description | | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | [Get organizations](https://learn.microsoft.com/en-us/graph/api/organization-get?view=graph-rest-1.0\&tabs=http) | `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](https://learn.microsoft.com/en-us/graph/api/user-list?view=graph-rest-1.0\&tabs=http) | `User.Read.All` `User.ReadWrite.All` `Directory.Read.All` `Directory.ReadWrite.All` | Pulls Teams users into Cortex | | [Get channels](https://learn.microsoft.com/en-us/graph/api/channel-list?view=graph-rest-1.0\&tabs=http) | `ChannelSettings.Read.Group` | Enables notifications | | [Get teams](https://learn.microsoft.com/en-us/graph/api/teams-list?view=graph-rest-1.0\&tabs=http) | `Team.ReadBasic.All` | Enables notifications to teams | | [Get team members](https://learn.microsoft.com/en-us/graph/api/team-list-members?view=graph-rest-1.0\&tabs=http) | `TeamMember.Read.Group` | Enables Scorecard rule for Teams | | [Send messages](https://learn.microsoft.com/en-us/graph/api/channel-post-messages?view=graph-rest-1.0\&tabs=http) | `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](https://app.getcortexapp.com/admin/settings/microsoftteams) in Cortex, click the [Microsoft AppSource](https://appsource.microsoft.com/en-us/product/teams-app/WA200005959) 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](https://admin.teams.microsoft.com/) 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](https://learn.microsoft.com/en-us/microsoftteams/teams-app-setup-policies#pin-apps). ### Limitations Cortex does not automatically discover MS Teams channels based on a [Cortex tag](https://docs.cortex.io/entities#cortex-tag) so you must [define channels for each entity](#editing-the-entity-descriptor) 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). ### Editing the entity descriptor To associate a Microsoft Teams channel with an entity, define a `x-cortex-microsoft-teams` block in an [entity descriptor](https://docs.cortex.io/entities#defining-entities-via-yaml-file) as shown in the example below. Defining a Teams channel will provide [direct access to the channel via the entity page](#viewing-microsoft-teams-information-across-cortex) in Cortex. ```yaml 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](https://docs.cortex.io/ingesting-data-into-cortex/entities/details): 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.\\
The MS Teams channels appear in the upper right side of an entity details page.
* You can write CQL queries and Scorecard rules based on Microsoft Teams channels. Learn more under [Scorecards and CQL](#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.
A notification in MS Teams includes actionable information.
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](https://docs.cortex.io/configure/settings/notifications#adjusting-your-personal-notification-subscriptions) 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](https://docs.cortex.io/configure/settings/notifications#enable-notifications-for-users-teams-and-entities). 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](https://docs.cortex.io/configure/settings/notifications). ### 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](https://app.getcortexapp.com/admin/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 ```
### View integration logs {% hint style="info" %} This feature is available to Cortex cloud customers. {% endhint %} On the integration settings page, click the **Logs** tab to view logs from the last 7 days. Learn more in [Troubleshooting with integration logs](https://docs.cortex.io/ingesting-data-into-cortex/integrations/..#troubleshooting-with-integration-logs). ## 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](https://www.cortex.io/legal/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?[​](https://docs.cortex.io/docs/reference/integrations/aws#still-need-help) The following options are available to get assistance from the Cortex Customer Engineering team: * **Email**: , or open a support ticket in the in app 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.