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
- Authentifizierung
- Routing-Konvention & Design-Prinzipien
- Projektstruktur
- Neue Notification hinzufĂĽgen (Schritt fĂĽr Schritt)
- Contract-Design
- E-Mail-Templates (MJML → cshtml)
- Anhänge
- Empfänger & Absender
- Mailversand je Umgebung
- Client-Library fĂĽr Consumer
- Testen
- Deployment & Konfiguration
- Checkliste
Ü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:
| Projekt | Zweck |
|---|---|
CCA.NotificationApi | Web-Host + Controller (Endpoints), Program.cs, DI |
CCA.NotificationApi.Abstractions | Request-Modelle (Contract, wird auch vom Client referenziert) |
CCA.NotificationApi.Core | Services (Rendering + Versand), Mail-Sender, TisPlatform-Config |
CCA.NotificationApi.EmailTemplates | ViewModels, Razor-Views (.cshtml), MJML-Quellen |
Tis.PlatformNotificationApi.Client | NuGet-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>.mjmlerstellen (Layout via mjml.io/try-it-live testen). - Nach HTML konvertieren, als
Views/TisPlatform/<Bereich>/<Name>.cshtmlablegen. - 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 ""→QueuePOST "preview"(Development) → HTML-PreviewGET ""/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). Quelleidentifiziert die sendende App ("TOGETHER Shell", …) — statt Quellsystem im Pfad.
Konventionen:
- Domain-Properties deutsch (PascalCase); Event-/Typnamen englisch.
- Datums-Property
RequestedAtalsDateTimeOffset. - ViewModel spiegelt Request; Rendering-Layout liegt im Template.
E-Mail-Templates (MJML → cshtml)​
- Workflow: MJML als Quelle pflegen → HTML generieren → als
.cshtmlablegen (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 beiwidth:248px; height:auto.
- Plattform (TOGETHER):
Anhänge​
EmailData.Attachments=EmailAttachmentData[]mit Base64-Content.- UnterstĂĽtzte Typen:
EmailDataAttachmentType→Png,Gif,Jpeg(behandelt inPickupDirectoryMailSenderServiceundSendGridMailSenderService). - 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ĂĽssel | Default | Verwendung |
|---|---|---|
DefaultEmailSender.Support | service@tis-cca.com | Absender Support |
DefaultEmailSender.InstallationsSupport | installations-support@tis-cca.com | Absender Installations-Support |
DefaultEmailSender.Usermanagement | usermanagement@tis-cca.com | Absender Benutzerverwaltung |
DefaultEmailReceiver.Kundenservice | otrs@tis-cca.com | OTRS/Kundenservice-Postfach |
Benachrichtigungen an den Kundenservice/Support gehen an das OTRS-Postfach.
Mailversand je Umgebung​
Gesteuert ĂĽber DefaultMailService:
| Wert | Verhalten |
|---|---|
SendGrid | Realer Versand (Prod/Fachtest) |
AzureCommunicationService | Realer Versand (Alternative) |
PickupDirectory | Development: 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.AccessTokenManagementv4 nutzt stark typisierte Werte (ClientId,ClientSecret,Scope,ClientCredentialsClientName) →.Parse(...).cca.notificationApiselbst nutzt für seinen ConfigServer-Client dasselbe Prinzip (Vorgänger-PaketIdentityModel.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 TestdatenPOST /notifications/<pfad>/preview→ HTML-Preview für konkreten RequestGET /notifications/<pfad>/sendTestmail→ Testmail (landet als.emlimmail_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,
--→:):Setzen (pro Environment-Vault):<Prefix>--NotificationApi--ClientSecret
# Beispiel Shell: Tis-Hosting-Shell--NotificationApi--ClientSecretaz 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.Clientautomatisch. Non-main-Branches erzeugen ein Prerelease-Paket (Version<BuildNumber>-<commitHash>). Voraussetzung: der Branch matcht den CI-Triggerfeatures/*(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.notificationApideployt 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/...),Quelleim 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)