# Phase 2 — Microsoft Teams Activity Feed Notifications

This is the setup guide for delivering Jira ticket updates to users' Microsoft Teams Activity Feed (the bell icon in Teams).

The backend code, frontend toggle, and Teams app manifest are already shipped. To turn the channel on, you only need to do **3 things in Microsoft 365** (one-time tenant setup) and **2 things on the server** (env var + restart).

---

## Part 1 — Microsoft 365 Tenant Setup (Tenant Admin)

### Step 1.1 — Add `TeamsActivity.Send` permission to your Entra app

1. Sign in to **https://entra.microsoft.com** as a **Global Administrator** (or Privileged Role Admin).
2. Go to **Applications → App registrations**.
3. Open the existing **"TMC Support Portal Notifier"** app registration.
   - This is the one whose Client ID is `532748be-a287-4718-87ad-db15278229a1` (currently has `Mail.Send` consented).
4. Click **API permissions** in the left sidebar.
5. Click **Add a permission**.
6. Choose **Microsoft Graph → Application permissions**.
7. Search for `TeamsActivity.Send`. Check it. Click **Add permissions**.
8. Back on the API permissions list, click **Grant admin consent for Therapy Management Corporation** (top of the permissions table).
9. Confirm the green checkmark appears next to `TeamsActivity.Send`.

> **Why this permission?** It lets the backend (running app-only) post into any tenant user's Activity Feed via the Graph endpoint `POST /users/{id}/teamwork/sendActivityNotification`.

---

### Step 1.2 — Sideload the TMC Support Teams app manifest

The Teams app is what shows up as the icon in the Activity Feed. Without it installed, notifications have no app to belong to and Graph will reject them.

**The manifest .zip file is at:** `/app/teams_app/tmc-support-teams-app.zip`

(After you `git pull` on the production server, it will be at `/var/www/html/support-portal/teams_app/tmc-support-teams-app.zip`. You can also download it from GitHub once committed.)

1. Sign in to **https://admin.teams.microsoft.com** as a **Teams Service Administrator** (or Global Admin).
2. Left sidebar → **Teams apps → Manage apps**.
3. Click **+ Upload new app**.
4. Click **Upload** in the dialog.
5. Select the **`tmc-support-teams-app.zip`** file.
6. Wait ~10 seconds for the app to appear in the list.
7. Click on **TMC Support** in the list.
8. **Copy the App ID** shown in the details pane (it's a GUID like `b30fc195-f057-44d0-ae3c-7fa246b94fc4`). **You will need this for Step 2.1.**
9. Confirm the app is allowed org-wide. On the app detail page, check the **"Available to"** field in the top card — it should read **"Everyone (org-wide default)"** (or a custom group, depending on your tenant's app permission policy). If it reads "No one" or "Blocked", you'll need to adjust your tenant's **org-wide app settings** under **Teams apps → Permission policies** to allow custom apps.

> **Note**: "Available to" governs whether the app *can* be installed by users — it's the equivalent of the "Allowed/Blocked" column you'll see if you go back to the **Manage apps** list view. "Installed for: No one" is normal at this point — it just means no one has installed it yet (which is fine; the Activity Feed notifications work app-only without user install once `TeamsActivity.Send` is admin-consented).

> **Note**: This sideloads the app at the **tenant** level. Users do NOT have to install it themselves for the Activity Feed channel to work — once `TeamsActivity.Send` is admin-consented in Step 1.1, the backend can post notifications to any user in the tenant whether or not they personally install the app. **However**, if the notification's deep link points to the Teams app tab (rather than the browser), the user needs the app pinned/installed for the click-through to open inside Teams.

---

### Step 1.3 *(optional, but recommended)* — Pre-install the app for all users via App Setup Policy

This makes the TMC Support Portal appear in everyone's Teams sidebar automatically (so the notification click-through opens **inside** Teams, not in a browser).

1. In the Teams Admin Center, go to **Teams apps → Setup policies**.
2. Click **Global (Org-wide default)**.
3. Under **Installed apps**, click **+ Add apps**.
4. Search for **TMC Support**. Add it.
5. Under **Pinned apps**, click **+ Add apps**. Add **TMC Support**. Drag it to your preferred position in the rail.
6. Click **Save**.

> Changes take up to 24 hours to propagate to users' Teams clients.

---

## Part 2 — Server Setup (One Command + One env var)

### Step 2.1 — Add `TEAMS_APP_ID` to backend/.env

1. SSH to the production server.
2. Edit `/var/www/html/support-portal/backend/.env`.
3. Add this line (replace the value with the App ID you copied in Step 1.2):
   ```
   TEAMS_APP_ID=b30fc195-f057-44d0-ae3c-7fa246b94fc4
   ```

### Step 2.2 — Pull and restart

```bash
cd /var/www/html/support-portal
git pull origin main
sudo supervisorctl restart support-backend
```

Verify by tailing the backend log — you should see:
```
notifications: teams channel enabled (app_id=b30fc195-...)
```

If you instead see `notifications: teams channel DISABLED — TEAMS_APP_ID not set`, the env var didn't load — check the `.env` file syntax (no quotes, no trailing spaces).

---

## Part 3 — User Verification

1. Open `https://support.therapymgmt.com` in a browser. Sign in.
2. Click the **bell** icon in the header.
3. In **Channels**, you should see **Microsoft Teams** with an active toggle (no longer "Coming in Phase 2").
4. Turn the toggle **ON**.
5. In the **What to notify me about** matrix, check at least one event under the Teams column (e.g. *"A ticket is assigned to me"*).
6. Click **Save**.
7. Click **Send test** next to Microsoft Teams.
8. Open Microsoft Teams (desktop or web). Click the **Activity** bell in the top-left rail.
9. You should see a new entry: *"TMC Support Portal — Test notification..."* within 5–15 seconds.

---

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| **"Send test" returns 503 "client_not_configured"** | `TEAMS_APP_ID` env var not loaded | Re-check `.env` and restart `support-backend` |
| **"Send test" returns 403** | `TeamsActivity.Send` permission not granted/consented | Re-do Step 1.1; confirm green check |
| **"Send test" returns 404 "no Microsoft user found"** | The address in the Teams channel is not a real M365 mailbox | Use the user's official `@therapymgmt.com` UPN |
| **Test test arrives in email but NOT Teams** | App not sideloaded yet | Re-do Step 1.2 |
| **Notification arrives but click does nothing** | App not installed for that user | Have them install **TMC Support** from the Teams app store, OR enable Step 1.3 (App Setup Policy) |
| **Backend log says `Graph sendActivityNotification 401`** | Token cache stale | The backend invalidates it automatically on 401; retry. If persistent, restart `support-backend` |

---

## What's Sent in the Notification (HIPAA design)

By policy, **no PHI or ticket content** is included in the Teams notification body. The user sees only:

- App icon: TMC Support
- Title (Reason): e.g. *"Ticket TMCSUPP-123 was assigned to you"*
- Preview text: e.g. *"A support ticket has been assigned to you."*
- Click → opens the TMC Support Portal tab, deep-linked to the ticket (which requires Microsoft sign-in).

Details (summary, comments, attachments) are only visible **after** the user authenticates into the portal — same model as the existing email channel.

---

## Files Touched

**Backend (already merged):**
- `backend/notifications/graph_teams.py` — new Graph client for `sendActivityNotification`
- `backend/notifications/config.py` — `TEAMS_APP_ID` env var
- `backend/notifications/prefs.py` — `teams_activity` channel added to allow-list + caches `microsoft_user_id`
- `backend/notifications/dispatcher.py` — routes the new channel
- `backend/notifications/router.py` — `GET /api/notification-prefs/teams-status` endpoint
- `backend/server.py` — startup wiring for `GraphTeamsClient`

**Frontend (already merged):**
- `frontend/public/js/notifications.js` — Teams toggle + matrix column + test button
- `frontend/public/support-portal.html` — Channel block + matrix column header

**Teams App Package:**
- `teams_app/manifest.json` — Teams app manifest (v1.16, includes RSC + activityTypes)
- `teams_app/color.png` / `outline.png` — App icons (placeholders — feel free to replace with real branding)
- `teams_app/tmc-support-teams-app.zip` — Ready-to-upload .zip

---

## What to Do If Tenant Admin Refuses

If your IT department says no to `TeamsActivity.Send` (broad permission), there's an alternative: use **resource-specific consent** instead. The manifest already declares `TeamsActivity.Send.User` (Application mode). Each user would then individually install the TMC Support app from the Teams catalog, granting their own consent. To switch to that mode:

1. In Step 1.1, **don't** grant `TeamsActivity.Send`. Instead, request `RSC.User.ReadWrite.All` (if your policy allows) OR have each user install the app personally.
2. After Step 1.2, publish the app to the Teams app catalog (Teams Admin Center → Manage Apps → click TMC Support → **Publish**).
3. Communicate to users: *"Install the **TMC Support** app from Teams to enable Teams notifications."*

Notifications will then only reach users who have explicitly installed the app, which is a stricter opt-in model but identical from the backend's perspective.