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

composer require sbp-jm/flarum-msteams-webhook:dev-main

Flarum Cache leeren

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

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

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:

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

extend.php
src/
  Listener/
    MirrorAlertsToTeams.php
  Job/
    SendTeamsActivityNotificationJob.php
  Service/
    GraphTokenProvider.php
    TeamsActivityNotifier.php
  Support/
    NotificationPayloadFactory.php
    TargetResolver.php