148 lines
4.4 KiB
Markdown
148 lines
4.4 KiB
Markdown
# flarum-msteams-webhook
|
|
|
|
Spiegelt Flarum-**Web-Benachrichtigungen** (die Glocke im Forum) in den **Microsoft Teams Activity Feed**.
|
|
|
|
## Zielbild
|
|
|
|
Diese erste Version registriert **keinen eigenen Teams-Kanal in der Flarum-UI**. Stattdessen spiegelt die Erweiterung exakt die Benachrichtigungen, die ein Benutzer bereits im **Web/Alert-Kanal** aktiviert hat, nach Teams.
|
|
|
|
Das ist für Flarum 1.8.x die pragmatischste v1, weil dadurch:
|
|
|
|
- die bestehende Flarum-Benachrichtigungslogik unverändert bleibt,
|
|
- keine Anpassung der Notification-Grid-UI notwendig ist,
|
|
- und Teams nur die Benachrichtigungen erhält, die im Forum ohnehin als Web-Alert ankommen würden.
|
|
|
|
## Kompatibilität
|
|
|
|
- Flarum: **^1.8**
|
|
- PHP: **^8.1**
|
|
- Getestetes Zielsystem laut Projekt-Hinweis: **Flarum 1.8.15**, **PHP 8.3.6**
|
|
|
|
## Was die Extension macht
|
|
|
|
1. Hängt sich per `Extend\Notification()->beforeSending(...)` in den Flarum-Notification-Flow ein.
|
|
2. Prüft für jeden Empfänger, ob die betreffende Notification im **Web-Kanal (`alert`)** aktiviert ist.
|
|
3. Löst dafür einen **Queue-Job** aus.
|
|
4. Der Queue-Job holt per **Client Credentials Flow** ein Graph-Token.
|
|
5. Anschließend wird per Microsoft Graph eine **Teams Activity Feed Notification** an den Benutzer gesendet.
|
|
|
|
## Voraussetzungen in Microsoft 365 / Entra / Teams
|
|
|
|
### 1) Entra App Registration
|
|
|
|
Benötigte Konfiguration:
|
|
|
|
- `tenant_id`
|
|
- `client_id`
|
|
- `client_secret`
|
|
|
|
Benötigte Microsoft Graph **Application Permission**:
|
|
|
|
- bevorzugt: `TeamsActivity.Send.User`
|
|
- alternativ: `TeamsActivity.Send`
|
|
|
|
### 2) Teams App
|
|
|
|
Die Ziel-Benutzer müssen die Teams-App installiert haben, für die Benachrichtigungen verschickt werden.
|
|
|
|
Empfehlung für v1:
|
|
|
|
- Activity Type: `systemDefault`
|
|
- Teams App ID in der Extension-Konfiguration hinterlegen
|
|
|
|
### 3) Benutzer-Mapping
|
|
|
|
Diese v1 unterstützt folgende Auflösungsstrategien:
|
|
|
|
- `email` → `POST /users/{email}/teamwork/sendActivityNotification`
|
|
- `upn` → UPN aus User-Preference oder Fallback auf E-Mail
|
|
- `preference` → frei konfigurierbarer User-Preference-Key
|
|
|
|
Wenn euer Entra-/SSO-Login bereits mit identischer E-Mail / UPN arbeitet, reicht meist `email` oder `upn`.
|
|
|
|
## Installation
|
|
|
|
### Composer
|
|
|
|
```bash
|
|
composer require sbp-jm/flarum-msteams-webhook:dev-main
|
|
```
|
|
|
|
### Flarum Cache leeren
|
|
|
|
```bash
|
|
php flarum cache:clear
|
|
```
|
|
|
|
## Konfiguration
|
|
|
|
Da diese v1 noch kein Admin-UI mitliefert, werden die Settings direkt in der Flarum-`settings`-Tabelle gepflegt.
|
|
|
|
### Pflicht-Settings
|
|
|
|
```sql
|
|
REPLACE INTO settings (`key`, `value`) VALUES
|
|
('sbp-jm-msteams-webhook.enabled', '1'),
|
|
('sbp-jm-msteams-webhook.tenant_id', 'DEIN-TENANT-ID'),
|
|
('sbp-jm-msteams-webhook.client_id', 'DEINE-CLIENT-ID'),
|
|
('sbp-jm-msteams-webhook.client_secret', 'DEIN-CLIENT-SECRET'),
|
|
('sbp-jm-msteams-webhook.forum_base_url', 'https://forum.example.tld'),
|
|
('sbp-jm-msteams-webhook.user_lookup_strategy', 'email'),
|
|
('sbp-jm-msteams-webhook.activity_type', 'systemDefault'),
|
|
('sbp-jm-msteams-webhook.timeout_seconds', '15');
|
|
```
|
|
|
|
### Optionale Settings
|
|
|
|
```sql
|
|
REPLACE INTO settings (`key`, `value`) VALUES
|
|
('sbp-jm-msteams-webhook.teams_app_id', 'DEINE-TEAMS-APP-ID'),
|
|
('sbp-jm-msteams-webhook.icon_id', ''),
|
|
('sbp-jm-msteams-webhook.upn_preference_key', 'sbp-jm-msteams-webhook.upn'),
|
|
('sbp-jm-msteams-webhook.user_preference_key', 'sbp-jm-msteams-webhook.target');
|
|
```
|
|
|
|
## Queue / Scheduler
|
|
|
|
Die Extension ist für asynchrone Zustellung ausgelegt.
|
|
|
|
Empfohlen:
|
|
|
|
```bash
|
|
php flarum queue:work
|
|
```
|
|
|
|
Wenn ihr bereits den **database** Queue Driver und einen aktiven Scheduler verwendet, passt diese Erweiterung sehr gut in euer bestehendes Setup.
|
|
|
|
## Bekannte Einschränkungen der v1
|
|
|
|
- Noch **kein Admin-UI** zum Setzen der Settings
|
|
- Noch **kein User-UI** für persönliches Teams-Ziel / Opt-out
|
|
- Noch **keine Teams-Spalte** im Flarum-Notification-Grid
|
|
- Activity Feed setzt voraus, dass die passende Teams-App im Zielkontext installiert ist
|
|
|
|
## Nächste sinnvolle Schritte
|
|
|
|
1. Admin-UI für Settings ergänzen
|
|
2. User-UI für Ziel-UPN / Opt-out ergänzen
|
|
3. Optional eine echte `Teams`-Spalte im Notification Grid ergänzen
|
|
4. Test-Command (`php flarum teams:test-user <userId>`) hinzufügen
|
|
5. Persistentes Delivery-Log ergänzen
|
|
|
|
## Projektstruktur
|
|
|
|
```text
|
|
extend.php
|
|
src/
|
|
Listener/
|
|
MirrorAlertsToTeams.php
|
|
Job/
|
|
SendTeamsActivityNotificationJob.php
|
|
Service/
|
|
GraphTokenProvider.php
|
|
TeamsActivityNotifier.php
|
|
Support/
|
|
NotificationPayloadFactory.php
|
|
TargetResolver.php
|
|
```
|