Microsoft Teams Integration

uControl Insight can post alerts and a daily AI digest to a Microsoft Teams channel via the companion uControl Teams bot. The integration is one-way (uControl → Teams) and uses an HTTPS webhook plus an optional HMAC shared secret.

What you get

• Scan failure alerts — whenever a discovery run completes with errors or fails entirely, the bot receives a payload from uControl and posts an Adaptive Card to the Teams channel summarising the failure, scan name, affected device count, error message and (if AI is enabled) the AI diagnosis with recommended actions.
• Daily AI Digest — one Adaptive Card per morning summarising the state of the estate: headline, highlights, recommended actions, confidence.
• On-demand digest — admins can fire a digest right now via the Send now button on /ai/insights.

Architecture

uControl Insight  ——HTTPS POST (JSON)——→  uControl Teams Bot  ——Bot Framework——→  Teams channel

The Teams bot is a separate Node.js service (deliverable: ucontrol-teams-app). Customers run it next to uControl Insight or on a public-facing host with ngrok. It registers as an Azure Bot in your tenant and is sideloaded as a Teams app.

Prerequisites

• A Microsoft 365 tenant with permission to register Azure Bots and sideload Teams apps.
• An always-on host or reverse-proxy/tunnel (e.g. ngrok) that can serve HTTPS to Microsoft.
• The ucontrol-teams-app package (Node.js 18+).

Step 1 — Set up the Teams bot

1. Register an Azure Bot. In the Azure portal, create a new Bot resource. Note the App ID (Microsoft App ID) and create a client secret. Set the messaging endpoint to https://YOUR-BOT-PUBLIC-HOST/api/messages.
2. Install the bot package on a host of your choice:

   git clone <ucontrol-teams-app repo>
   cd ucontrol-teams-app
   npm install
   cp .env.example .env
   # Set MICROSOFT_APP_ID, MICROSOFT_APP_PASSWORD, PORT (default 3978)
   npm run build
   node dist/index.js

3. Expose the bot publicly. If you're behind NAT, use ngrok:

   ngrok http 3978

   Take the https://….ngrok-free.dev URL and update the Azure Bot messaging endpoint to https://….ngrok-free.dev/api/messages.
4. Sideload into Teams. Open Teams → Apps → Manage your apps → Upload an app → Upload a custom app. Use the manifest .zip shipped with the bot package. Add the app to the channel you want alerts in.
5. Send the bot a "register" message in Teams — the bot records that channel as the destination for future alerts.

Step 2 — Configure uControl Insight

1. Log in as an administrator.
2. Sidebar → Settings → Notifications tab.
3. Tick Teams notifications enabled.
4. In Webhook URL, paste the bot's alert endpoint, e.g. https://your-bot.example.com/api/ucontrol/alerts (or the ngrok URL for testing).
5. Optionally set a Shared secret (HMAC) — the bot validates the x-ucontrol-secret header on inbound POSTs. If set, the value is AES-GCM encrypted at rest in uControl using the master key.
6. Set Base URL to your uControl Insight URL (e.g. https://ucontrol.example.com/uControlInsight). Teams cards include "Open in uControl" links pointing back here.
7. Click Save notification settings.

Changes here apply on the next outbound notification — no service restart required.

Step 3 — Verify

1. From AI → Insights, click Send now on the Daily AI Digest card. Within seconds a card should appear in the Teams channel.
2. If nothing arrives, check:
   • The bot console / log shows the POST being received.
   • If a shared secret is set on both sides, the values match exactly.
   • Azure Bot resource is healthy in the Azure portal.
   • The webhook URL is reachable from the uControl server — cu​rl -X POST -H "Content-Type: application/json" -d '{"eventType":"test"}' <webhook-url> should return a non-error.

What gets sent — payload reference

Each POST body contains an eventType field, a summary, and additional context fields depending on the event:

Disabling

To stop notifications without removing the configuration, untick Teams notifications enabled on the Settings → Notifications panel and save. Re-enable any time — no restart needed.