4.4 KiB

Raw Blame History

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

Hängt sich per Extend\Notification()->beforeSending(...) in den Flarum-Notification-Flow ein.
Prüft für jeden Empfänger, ob die betreffende Notification im Web-Kanal (alert) aktiviert ist.
Löst dafür einen Queue-Job aus.
Der Queue-Job holt per Client Credentials Flow ein Graph-Token.
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.

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

Admin-UI für Settings ergänzen
User-UI für Ziel-UPN / Opt-out ergänzen
Optional eine echte Teams-Spalte im Notification Grid ergänzen
Test-Command (php flarum teams:test-user <userId>) hinzufügen
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

4.4 KiB Raw Blame History