Zum Hauptinhalt springen

Platform Notifications (TIS)

🤖 Generated with Claude Code

⚠️ Not yet reviewed

Co-Authored-By: Claude (noreply@anthropic.com)

Leitfaden für TIS Platform Notifications – E-Mail-Benachrichtigungen, die von Plattform-Apps über die zentrale cca.notificationApi verschickt werden (z.B. MFA-Code, Passkey-Aktivierung, Benutzerverwaltung an OTRS, Support-Anfragen).

Inhalt​


Überblick & Architektur​

Zentrale API: cca.notificationApi (ASP.NET Core, .NET 8). Eine Plattform-App schickt einen typisierten Request; die API rendert daraus eine E-Mail (Razor/MJML) und versendet sie ĂĽber den konfigurierten Mail-Sender.

Deployte Instanz (environment-unabhängig, ein reales System):

https://notification.api.cca.online/

Projekte im Repo:

ProjektZweck
CCA.NotificationApiWeb-Host + Controller (Endpoints), Program.cs, DI
CCA.NotificationApi.AbstractionsRequest-Modelle (Contract, wird auch vom Client referenziert)
CCA.NotificationApi.CoreServices (Rendering + Versand), Mail-Sender, TisPlatform-Config
CCA.NotificationApi.EmailTemplatesViewModels, Razor-Views (.cshtml), MJML-Quellen
Tis.PlatformNotificationApi.ClientNuGet-Client fĂĽr Consumer (IPlatformNotificationApiClient)

Datenfluss:

App → (client_credentials-Token) → POST /notifications/... → Service rendert Razor/MJML
→ IMailSenderService (SendGrid | PickupDirectory | AzureCommunicationService) → Empfänger

Authentifizierung​

  • OAuth2 client_credentials, Authority https://www.servicebytogether.at/identity.server.
  • Erforderlicher Scope: notification.tis-platform.
  • Policy auf allen Platform-Endpoints: [Authorize("CanQueueTisPlatformNotifications")].
  • Consumer brauchen einen IdentityServer-Client mit diesem Scope (z.B. tis.platformNotifications.client).

Der Token-Endpoint ist environment-unabhängig derselbe (Prod-IdentityServer), weil es faktisch eine Notification-API + ein reales OTRS-Postfach gibt.


Routing-Konvention & Design-Prinzipien (MUSS / SOLLTE)​

Historisch liegen Routen unter dem Absendersystem:

notifications/tis.identityServer/twofactor/code
notifications/tis.identityServer/passkeys/activationLink
notifications/tis.identityServer/kundenservice/accountCreated

Neue Routen SOLLTEN zweck- bzw. fähigkeitsbasiert auf Plattform-Ebene liegen (tis.platform):

notifications/tis.platform/support

Warum zweckbasiert statt quellsystem-basiert?​

  • Quellsysteme wandern (z.B. tis.identityServer → Tis.Identity.Api) → der Pfad wird irrefĂĽhrend. Ein zweckbasierter Pfad bleibt stabil.
  • Mehrere Apps können denselben Notification-Typ senden. Die sendende App MUSS in den Payload (Feld Quelle) und DARF NICHT in den Pfad.
  • Entspricht dem Vorgehen etablierter Notification-Plattformen (SendGrid, Twilio, Courier, …): Routing nach Typ/Zweck, Absender & Empfänger sind Metadaten/Konfiguration.

Projektstruktur​

Gruppierung nach Bereich unter TisPlatform (bzw. TisTemplates bei MJML):

CCA.NotificationApi.Abstractions/Models/TisPlatform/<Bereich>/<Name>NotificationRequest.cs
CCA.NotificationApi.Core/TisPlatform/<Bereich>/<Name>NotificationService.cs (+ Interface)
CCA.NotificationApi.EmailTemplates/Models/TisPlatform/<Bereich>/<Name>ViewModel.cs
CCA.NotificationApi.EmailTemplates/Views/TisPlatform/<Bereich>/<Name>.cshtml
CCA.NotificationApi.EmailTemplates/_mjml_templates/TisTemplates/<Bereich>/<Name>.mjml
CCA.NotificationApi/TisPlatform/<Name>Controller.cs

Beispiel-Bereiche: IdentityServer, Kundenservice, Support.


Neue Notification hinzufügen (Schritt für Schritt)​

Referenz-Implementierung: Support (notifications/tis.platform/support).

1. Request-Modell (Abstractions)​

Models/TisPlatform/<Bereich>/<Name>NotificationRequest.cs — deutsche PascalCase-Properties, Datums-Feld als DateTimeOffset (Konvention: RequestedAt), Pflichtfelder mit [Required].

2. ViewModel (EmailTemplates)​

Models/TisPlatform/<Bereich>/<Name>ViewModel.cs — spiegelt das Request-Modell (gleiche Feldstruktur). Nicht im Service in eine generische Liste flatten. Formatierungen als abgeleitete Properties, z.B.:

public DateTimeOffset RequestedAt { get; set; }
public string Timestamp => RequestedAt.ToString("dd.MM.yyyy HH:mm:ss");

3. MJML-Quelle + Razor-View​

  • MJML in _mjml_templates/TisTemplates/<Bereich>/<Name>.mjml erstellen (Layout via mjml.io/try-it-live testen).
  • Nach HTML konvertieren, als Views/TisPlatform/<Bereich>/<Name>.cshtml ablegen.
  • Model-Bindung via @Model.[Property], Layout im Template (nicht im Service).

4. Service + Interface (Core)​

TisPlatform/<Bereich>/<Name>NotificationService.cs — mappt Request → ViewModel, rendert über IRazorViewToStringRenderer, baut EmailData (From/Receipient/Subject/ Attachments) und ruft IMailSenderService.SendEmailToUser(...). Standardmethoden: Queue(request) und GeneratePreview(request).

5. DI-Registrierung​

In Core/TisPlatform/ServiceCollectionExtensions.AddTisPlatformNotifications(...) den Service registrieren.

6. Controller (Endpoint)​

TisPlatform/<Name>Controller.cs mit [Authorize("CanQueueTisPlatformNotifications")]:

  • POST "" → Queue
  • POST "preview" (Development) → HTML-Preview
  • GET "" / GET "sendTestmail" (Development) → Preview/Testmail mit Testdaten

7. Client-Methode (MUSS)​

Im Tis.PlatformNotificationApi.Client MUSS eine Methode ergänzt werden, damit Consumer den geteilten Contract nutzen statt HTTP/DTO handzuschreiben (kein Contract-Drift) → siehe Client-Library.


Contract-Design​

Bewährtes Muster (am Beispiel Support):

  • Strukturierte Pflichtfelder: Betreff, Beschreibung, Quelle, BenutzerId, RequestedAt, Umgebung.
  • Optionale strukturierte Felder: Benutzername, MaklerId, TisSessionId, TisCorrelationId (AppInsights-Operation-Id des fehlerverursachenden Requests, fĂĽr 2nd/3rd-Level-Support).
  • Freier Zusatz-Kontext: Kontext (Dictionary<string,string>) fĂĽr app-spezifische Infos, die nicht Teil des stabilen Contracts sind (z.B. aktiver Tab, Leistungsstufe).
  • Quelle identifiziert die sendende App ("TOGETHER Shell", …) — statt Quellsystem im Pfad.

Konventionen:

  • Domain-Properties deutsch (PascalCase); Event-/Typnamen englisch.
  • Datums-Property RequestedAt als DateTimeOffset.
  • ViewModel spiegelt Request; Rendering-Layout liegt im Template.

E-Mail-Templates (MJML → cshtml)​

  • Workflow: MJML als Quelle pflegen → HTML generieren → als .cshtml ablegen (siehe _mjml_templates/README.MD).
  • Branding: Segoe UI, Akzentfarbe #f39200, weiĂźer Container auf grauem Hintergrund.
  • Logo (CDN Styleguide):
    • Plattform (TOGETHER): https://cdn.togethercca.com/styleguide/assets/products/together/logo-64.png
    • Produkt CCA: .../products/together-cca/logo-64.png
    • Varianten logo-32 / logo-64; die 64er skaliert wirkt auf Retina schärfer. Beispiel: logo-64 (496Ă—64) angezeigt bei width:248px; height:auto.

Anhänge​

  • EmailData.Attachments = EmailAttachmentData[] mit Base64-Content.
  • UnterstĂĽtzte Typen: EmailDataAttachmentType → Png, Gif, Jpeg (behandelt in PickupDirectoryMailSenderService und SendGridMailSenderService).
  • Screenshot-Beispiel: Content-Type auf den passenden Enum-Wert mappen; Default Png.

Empfänger & Absender​

Konfiguriert ĂĽber TisPlatformNotificationOptions (DefaultEmailSender / DefaultEmailReceiver, Defaults in Core/TisPlatform/Configuration/DefaultEmailSender.cs):

SchlĂĽsselDefaultVerwendung
DefaultEmailSender.Supportservice@tis-cca.comAbsender Support
DefaultEmailSender.InstallationsSupportinstallations-support@tis-cca.comAbsender Installations-Support
DefaultEmailSender.Usermanagementusermanagement@tis-cca.comAbsender Benutzerverwaltung
DefaultEmailReceiver.Kundenserviceotrs@tis-cca.comOTRS/Kundenservice-Postfach

Benachrichtigungen an den Kundenservice/Support gehen an das OTRS-Postfach.


Mailversand je Umgebung​

Gesteuert ĂĽber DefaultMailService:

WertVerhalten
SendGridRealer Versand (Prod/Fachtest)
AzureCommunicationServiceRealer Versand (Alternative)
PickupDirectoryDevelopment: schreibt .eml nach wwwroot/App_Data/mail_debug/ (kein realer Versand)

In Development wird also nichts versendet – die .eml (inkl. Anhang) landet lokal und kann mit Outlook/Thunderbird geöffnet werden.


Client-Library für Consumer​

Paket Tis.PlatformNotificationApi.Client (netstandard2.1) stellt IPlatformNotificationApiClient bereit (.Identity, .Kundenservice, .Support) und teilt die Contract-Typen aus CCA.NotificationApi.Abstractions.

Empfehlung: Consumer nutzen immer diesen Client + den geteilten Contract (kein handgeschriebenes HTTP/DTO → kein Contract-Drift).

Referenz-Integration (wie tis.identity)​

Dies ist das kanonische Muster – statischer, langlebiger ApiKey (Bearer-Token) aus dem Key Vault.

1. PackageReference (*.csproj):

<PackageReference Include="Tis.PlatformNotificationApi.Client" Version="1.0.*" />

2. Registrierung (Startup/DI):

services.AddPlatformNotificationsClient(configureHttpClient: client =>
{
var section = config.GetRequiredSection("TisPlatformNotificationsApi");
client.BaseAddress = new Uri(section.GetValue<string>("BaseAddress"));
client.SetBearerToken(section.GetValue<string>("ApiKey"));
});

3. Konfiguration (appsettings.json, ApiKey aus Key Vault):

"TisPlatformNotificationsApi": {
"BaseAddress": "https://notification.api.cca.online/",
"ApiKey": "@Microsoft.KeyVault(VaultName=...;SecretName=<prefix>--TisPlatformNotificationsApi--ApiKey)"
}

4. Nutzung (IPlatformNotificationApiClient injizieren):

public SendEmailModel(IPlatformNotificationApiClient client) { _client = client; }

await _client.Identity.QueuePasskeyActivationLinkNotification(request);
// bzw. _client.Kundenservice.* / _client.Support.QueueSupportMessageNotification(request)

Alternative: client_credentials via Duende.AccessTokenManagement​

AddPlatformNotificationsClient gibt einen IHttpClientBuilder zurück → statt eines statischen ApiKey können kurzlebige Tokens automatisch bezogen/gecached/erneuert werden (Scope notification.tis-platform). Empfohlen mit Duende.AccessTokenManagement – die TOGETHER Shell nutzt genau diesen Weg (kein handgeschriebener DelegatingHandler nötig):

var tokenClient = ClientCredentialsClientName.Parse("notification");
services.AddClientCredentialsTokenManagement()
.AddClient(tokenClient, c =>
{
c.TokenEndpoint = new Uri(cfg["NotificationApi:TokenEndpoint"]!);
c.ClientId = ClientId.Parse(cfg["NotificationApi:ClientId"]!);
c.ClientSecret = ClientSecret.Parse(cfg["NotificationApi:ClientSecret"]!);
c.Scope = Scope.Parse(cfg["NotificationApi:Scope"]!);
});

services.AddPlatformNotificationsClient(c => c.BaseAddress = new Uri(cfg["NotificationApi:BaseAddress"]!))
.AddClientCredentialsTokenHandler(tokenClient);

Duende.AccessTokenManagement v4 nutzt stark typisierte Werte (ClientId, ClientSecret, Scope, ClientCredentialsClientName) → .Parse(...). cca.notificationApi selbst nutzt für seinen ConfigServer-Client dasselbe Prinzip (Vorgänger-Paket IdentityModel.AspNetCore).

Beim Anlegen eines neuen Notification-Typs die Client-Methode ergänzen und eine neue (Prerelease-)Paketversion publizieren, damit Consumer sie referenzieren können (siehe Deployment).


Testen​

Development-Endpoints (nur IsDevelopment):

  • GET /notifications/<pfad> → HTML-Preview mit Testdaten
  • POST /notifications/<pfad>/preview → HTML-Preview fĂĽr konkreten Request
  • GET /notifications/<pfad>/sendTestmail → Testmail (landet als .eml im mail_debug)

Für Anhänge im Test: optionale Asset-Datei im Content-Root ablegen (Support-Beispiel: CCA.NotificationApi/TestData/support-test-screenshot.png) – wird zur Laufzeit gelesen, kein Rebuild nötig. Keine sensiblen Daten in Test-Assets/.eml einchecken.


Deployment & Konfiguration​

  • Endpoint & Token-Endpoint sind environment-unabhängig (eine API + ein Prod-IdentityServer).
  • Consumer-Secret (client_credentials) gehört in den Key Vault, nicht in appsettings. Namenskonvention (prefix-basiertes Laden, -- → :):
    <Prefix>--NotificationApi--ClientSecret
    # Beispiel Shell: Tis-Hosting-Shell--NotificationApi--ClientSecret
    Setzen (pro Environment-Vault):
    az keyvault secret set --vault-name at-tgca-tis-<d|f|p>-default \
    --name 'Tis-Hosting-Shell--NotificationApi--ClientSecret' --file secret.txt
  • Client-Paket / Prerelease: Die Pipeline packt & published Tis.PlatformNotificationApi.Client automatisch. Non-main-Branches erzeugen ein Prerelease-Paket (Version <BuildNumber>-<commitHash>). Voraussetzung: der Branch matcht den CI-Trigger features/* (Plural!) — feature/... (Singular) triggert nicht. So können Consumer eine neue Client-Methode schon vor dem Merge testen.
  • Reihenfolge beim Rollout eines neuen Typs: Es MUSS zuerst cca.notificationApi deployt werden (der Endpoint muss existieren), dann das Client-Paket publiziert und erst danach die Consumer-App ausgerollt werden.

Checkliste für einen neuen Notification-Typ (MUSS)​

  • Request-Modell in Abstractions (Pflichtfelder, RequestedAt, ggf. Kontext)
  • ViewModel spiegelt Request
  • MJML-Quelle + .cshtml (Branding, Logo, Layout im Template)
  • Service + Interface (Queue + GeneratePreview)
  • DI in AddTisPlatformNotifications
  • Controller mit CanQueueTisPlatformNotifications (+ Dev-Preview/Testmail)
  • Route zweckbasiert (tis.platform/...), Quelle im Payload
  • Absender/Empfänger in DefaultEmailSender/DefaultEmailReceiver
  • Anhang-Typen abgedeckt (Png/Gif/Jpeg)
  • Client-Methode in Tis.PlatformNotificationApi.Client + Paket publiziert
  • Consumer: Scope notification.tis-platform, Secret im Key Vault
  • Getestet via Dev-Preview / sendTestmail (mail_debug)