From 89582233bc8dc62414e605c8dbbc6b6aeadf396a Mon Sep 17 00:00:00 2001 From: Saiprasad Potdar Date: Wed, 28 Oct 2026 15:57:33 +0530 Subject: [PATCH] docs(notifications): connect Teams from Nubi's welcome card, and newer Teams behaviour - Setup: add Nubi first, then connect either from the welcome card's Connect Microsoft Teams button (no Microsoft sign-in; only the person who added Nubi, as a NudgeBee admin, within 7 days) or from Admin -> Integrations with Microsoft sign-in. - Using Nubi: alert threads use the alert's account; each thread message runs as its writer; approvals are recorded as the clicker; Nubi can post an approved message to a channel; what Ask Nubi says when it can't analyze. - Picker shows the default channel as "General (default channel)". - On-prem: MS_TEAMS_ACTION_SIGNING_KEY also enables the card's Connect button. - Troubleshooting for the Connect button's messages. Signed-off-by: Saiprasad Potdar --- .../integrations/Notifications/msteams.md | 71 ++++++++++++++----- 1 file changed, 54 insertions(+), 17 deletions(-) diff --git a/doc-server/docs/integrations/Notifications/msteams.md b/doc-server/docs/integrations/Notifications/msteams.md index 18f839bf..4006d3ef 100644 --- a/doc-server/docs/integrations/Notifications/msteams.md +++ b/doc-server/docs/integrations/Notifications/msteams.md @@ -12,16 +12,9 @@ A [webhook target](./webhook_targets.md) posts notifications through the channel ## Set up Microsoft Teams -Setup has three steps. The first is done once per workspace; the second once per team. +Setup has three steps. You add Nubi once per team, and connect your Microsoft tenant once per workspace. -### Step 1. Connect your Microsoft tenant - -1. In NudgeBee, go to **Admin → Integrations → Microsoft Teams** and click **Connect**. -2. Sign in with your Microsoft work account. NudgeBee asks only to sign you in and read your basic profile (`openid`, `profile`, `User.Read`). It gets no access to your directory, chats or channels. - -This links your Microsoft 365 tenant to your NudgeBee workspace. A Microsoft tenant can be connected to one NudgeBee workspace at a time. - -### Step 2. Add Nubi to your teams +### Step 1. Add Nubi to your teams 1. In Teams, open **Apps**, search for **Nubi**, and click **Add**. 2. Choose **Add to a team** and pick the team and channel. Nubi posts a welcome card there. @@ -29,10 +22,35 @@ This links your Microsoft 365 tenant to your NudgeBee workspace. A Microsoft ten If your organization manages which apps people can add, a Teams admin allows Nubi once in the **Teams admin center → Teams apps → Manage apps**. +### Step 2. Connect your Microsoft tenant + +This links your Microsoft 365 tenant to your NudgeBee workspace. A Microsoft tenant can be connected to one NudgeBee workspace at a time. There are two ways to do it. + +#### From Nubi's welcome card (no Microsoft sign-in) + +Use this when your organization doesn't let people approve apps that ask them to sign in with Microsoft. + +1. On the welcome card Nubi posted in Step 1, click **Connect Microsoft Teams**. +2. If NudgeBee asks you to sign in, sign in and then click the button on the card again. +3. NudgeBee shows the team and your workspace. Click **Connect**. + +The button only works for someone who meets **both** of these conditions: +- They **added Nubi to the team**, and are signed in to NudgeBee with the same email address they use to sign in to Microsoft. +- They are **a NudgeBee admin**, or have a role that can manage messaging integrations. + +It works for 7 days. After that, or for anyone else, connect from NudgeBee instead (below). + +Some people who add Nubi get a welcome card that points to **Admin → Integrations** instead of a Connect button: guests, personal Microsoft accounts, and accounts on a public email domain or an `onmicrosoft.com` address. + +#### From NudgeBee, with Microsoft sign-in + +1. In NudgeBee, go to **Admin → Integrations → Microsoft Teams** and click **Connect**. +2. Sign in with your Microsoft work account. NudgeBee asks only to sign you in and read your basic profile (`openid`, `profile`, `User.Read`). It gets no access to your directory, chats or channels. + ### Step 3. Choose where notifications go 1. In NudgeBee, go to **Admin → Integrations → Microsoft Teams → Channel-Account Mappings**. -2. Map each channel to the cloud accounts whose alerts it should get. Only teams that have Nubi are listed. +2. Map each channel to the cloud accounts whose alerts it should get. Only teams that have Nubi are listed. A team's default channel is listed as **General (default channel)**. 3. Click **Test Notification** to check delivery. Use [Notification Rules](../../features/notifications.md) to fine-tune which alerts go where. @@ -43,9 +61,18 @@ Use [Notification Rules](../../features/notifications.md) to fine-tune which ale ## Using Nubi in Teams -- **Ask a question.** Mention `@Nubi` in a channel or a thread, or message Nubi directly. If you have access to more than one account, Nubi asks which one to use. In a channel mapped to an account, or in an alert's thread, it uses that account straight away. +- **Ask a question.** Mention `@Nubi` in a channel or a thread, or message Nubi directly. If you have access to more than one account, Nubi asks which one to use. In a channel mapped to an account, it uses that account straight away. In an alert's thread, it always uses the alert's account; if you can't access that account, Nubi tells you instead of answering. +- **Share a thread.** Each message in a thread is answered as the person who wrote it, with that person's access. Someone without access to the thread's account is told so. - **Act on alerts.** Alert cards have **Ask Nubi**, which posts an analysis in the card's thread, and **Suppress…**, which creates a suppression rule. Suppressing needs an account admin role. -- **Approve workflows.** An approval card has one button per option the automation offers (a choice list and **Submit** when there are more than three). You need edit access to the account. An already-answered request shows *This approval was already answered.*; an expired one shows *This approval request has expired.* +- **When Ask Nubi can't analyze.** If the alert's last analysis failed, **Ask Nubi** runs it again. When it still can't finish, the thread says why and the card shows *Nubi couldn't analyze this alert*: + - the analysis failed: there's a link to the alert, where **Refresh investigation** runs it again; + - your workspace's AI budget is used up: see [Budgets and limits](../../features/ai/budgets-and-limits.md#when-a-limit-is-reached); + - the alert no longer exists; + - Nubi is busy with other alerts. + + An analysis on hold says what it's waiting for. One that is still running after 20 minutes gets a link to follow it in NudgeBee. +- **Approve workflows.** An approval card has one button per option the automation offers (a choice list and **Submit** when there are more than three). Your click is recorded as you, so you need edit access to the account or permission to run workflows on it. An already-answered request shows *This approval was already answered.*; an expired one shows *This approval request has expired.* +- **Post a message.** Ask Nubi to post a message to a Teams channel. Nubi shows you the exact message to approve first, then posts it signed *Sent by <your name> via Nubi*. These messages appear in [Delivery history](../../features/notifications.md#delivery-history) as sent from Nubi. - **Suppress durations.** **Suppress…** offers this alert for 1 h, 4 h, 24 h or 7 days, or every alert of the type for 4 h, 24 h or 7 days. - **Rate answers** with **👍 Helpful** / **👎 Not helpful**. Very long analyses are cut, with a link to the full one in NudgeBee. - **Cards expire.** Buttons on a card more than 7 days old no longer work; open the alert in NudgeBee instead. @@ -104,7 +131,7 @@ MS_TEAMS_BOT_TENANT_ID: The Directory (tenant) ID from Step 1, the bot's home te MS_TEAMS_ACTION_SIGNING_KEY: A random string that signs the data on card buttons, for example the output of `openssl rand -hex 32`. ``` -Without `MS_TEAMS_ACTION_SIGNING_KEY`, cards are sent without buttons. Restart the NudgeBee server pods after updating the secrets. +Without `MS_TEAMS_ACTION_SIGNING_KEY`, cards are sent without buttons, and the welcome card has no **Connect Microsoft Teams** button, so connect from **Admin → Integrations** instead. Restart the NudgeBee server pods after updating the secrets. ### Step 4. Create the Teams app package @@ -123,24 +150,34 @@ Then follow [Set up Microsoft Teams](#set-up-microsoft-teams) above. ### 2. Connect fails with "This Microsoft tenant is already connected to another workspace" * **Root Cause**: A Microsoft tenant can be connected to only one NudgeBee workspace. -* **Remediation**: Disconnect Microsoft Teams in the other workspace first, then connect again. +* **Remediation**: Disconnect Microsoft Teams in the other workspace first, then connect again. From the welcome card, the same case shows *This Microsoft tenant is connected to another NudgeBee workspace. Contact support to move it.* --- ### 3. A team or channel is missing from the channel picker * **Root Cause**: Nubi hasn't been added to that team, or the channel is private or shared. -* **Remediation**: Add Nubi to the team (Step 2), then reload the page. Use a standard channel. +* **Remediation**: Add Nubi to the team (Step 1), then reload the page. Use a standard channel. + +--- + +### 4. The welcome card's Connect button doesn't connect +* **Symptom**: After clicking **Connect Microsoft Teams** on Nubi's welcome card, NudgeBee shows one of these: + * *This link is for the person who added Nubi to this team.* You're signed in to NudgeBee with a different email from the person who added Nubi. Sign in with their account, or [connect from NudgeBee](#from-nudgebee-with-microsoft-sign-in). + * *Only a NudgeBee admin can connect Microsoft Teams.* Ask a NudgeBee admin to connect, or to give you a role that can manage messaging integrations. + * *This link has expired.* The button works for 7 days. [Connect from NudgeBee](#from-nudgebee-with-microsoft-sign-in) instead. + * *Your workspace changed in another tab.* Click the button on the card again. +* **No button on the card**: the person who added Nubi is a guest, uses a personal Microsoft account, or uses a public email domain or an `onmicrosoft.com` address. On-prem, the server may also be missing `MS_TEAMS_ACTION_SIGNING_KEY`. [Connect from NudgeBee](#from-nudgebee-with-microsoft-sign-in) instead. --- -### 4. Sign-In Fails with `Redirect URI Mismatch` (AADSTS50011), on-prem +### 5. Sign-In Fails with `Redirect URI Mismatch` (AADSTS50011), on-prem * **Symptom**: Connecting returns `AADSTS50011: The reply URL specified in the request does not match the reply URLs configured for the application`. * **Root Cause**: The redirect URI in Microsoft Entra ID doesn't match the public HTTPS base URL of your NudgeBee server. * **Remediation**: In Entra ID **App registrations → Authentication → Web Redirect URIs**, make sure the URI is exactly `https:///api/integrations/ms-teams/callback`, with no trailing slash and the same protocol. --- -### 5. Notifications Stopped Working / Expired Client Secret, on-prem +### 6. Notifications Stopped Working / Expired Client Secret, on-prem * **Symptom**: Notifications were working but now fail, and the logs show `401 Unauthorized` from Microsoft. * **Root Cause**: The app registration's client secret expired. * **Remediation**: