Notification Configuration

Notifications informieren Mitarbeiter über wichtige Ereignisse wie neue Schichten, Verfügbarkeitseingaben oder Absagen. Diese Anleitung erklärt die zwei Ebenen: Team-Trigger (Admin-gesteuert) und User-Präferenzen (Mitarbeiter-gesteuert).

Für Admins

Zwei Notification-Ebenen verstehen

Notifications in Shifty funktionieren auf zwei Ebenen:

1. Team-Trigger (Admin konfiguriert)

• Welche Events generieren Benachrichtigungen? (z.B. "Schedule wurde veröffentlicht")
• Wann werden sie gesendet? (Cron-Pattern, z.B. täglich um 9 Uhr)
• An wen? (E-Mail, Push, beides)

2. User-Preferences (Mitarbeiter konfiguriert)

• Möchte ich diese Benachrichtigung erhalten?
• Lieber per E-Mail oder Push?
• Oder gar nicht?

Zusammenhang:

Team-Trigger: "Schedule Published Events" mit E-Mail + Push

User-Preference: Max möchte "Schedule Published Events" NUR per E-Mail
                (nicht per Push)

Auswirkung: Max erhält E-Mail, aber keine Push-Nachricht ✅

Team-Level: Trigger-Konfiguration

Team-Trigger werden unter Admin > System > Team-Einstellungen im Abschnitt Notifications konfiguriert.

1. Availability Reminder (Verfügbarkeitserinnerung)

Auswirkung:

• System sendet Erinnerung: "Bitte gib deine Verfügbarkeit für nächste Woche ein"

Cron Pattern Beispiele:

• 0 9 * * 1 — Montag, 9:00 Uhr
• 0 18 * * 0 — Sonntag, 18:00 Uhr
• 0 8 1 * * — Jeden 1. Tag des Monats, 8:00 Uhr
• */30 * * * * — Alle 30 Minuten

Wenn Availabilities Disabled:
Diese Erinnerung wird nicht gesendet, egal wie die Trigger konfiguriert sind.

2. Assignment Reminder (Schichterinnerung)

Auswirkung:

• System sendet Erinnerung: "Deine Schichten nächste Woche: Montag 8–16 Uhr, Dienstag 10–14 Uhr"

3. Published Events Notification (Event-Veröffentlichung)

"direct" vs. "scheduled":

• direct: Wenn Admin ein Event veröffentlicht → sofort Benachrichtigungen sendet (real-time)
• scheduled: Benachrichtigungen werden zum Cron-Zeitpunkt gesammelt und versendet (z.B. täglich 18 Uhr ein Batch)

direct-Beispiel:

Admin veröffentlicht Event um 14:30 Uhr
→ Mitarbeiter erhalten sofort Push + E-Mail

scheduled-Beispiel:

Admin veröffentlicht Event um 14:30 Uhr
Cron Pattern: "0 18 * * *" (täglich 18 Uhr)
→ Mitarbeiter erhalten um 18:00 Uhr eine Benachrichtigung

User-Level: Preferences

Mitarbeiter konfigurieren ihre Benachrichtigungspräferenzen unter:
Mein Konto > Einstellungen > Benachrichtigungen

Verfügbare Notification-Typen

Diese Typen können Mitarbeiter einzeln konfigurieren:

Legende:

• ✓ = Mitarbeiter kann zwischen E-Mail/Push wählen
• — = Option nicht verfügbar für diesen Typ
• Push-only = Nur Push möglich (z.B. für interne Admin-Nachrichten)

Defaults & Optouts

Admin kann nicht zwingen:

• Admins können Trigger konfigurieren, aber jeder Mitarbeiter entscheidet am Ende selbst
• Wenn Mitarbeiter "Event Published" auf "Push aus" stellt, erhält er keine Push-Nachrichten (aber ggfs. E-Mails, wenn E-Mail AN ist)

Defaults:

• Die meisten Typen sind standardmäßig E-Mail + Push AN
• ADMIN_ASSIGNMENT_CANCELED ist nur Push AN (push-only Typ)

Zweck: Wann wird was gesendet?

Szenario 1: Vorausschauende Planung

Montag, 8 Uhr:
  - Admin hat Events für nächste Woche veröffentlicht
  - Cron: "0 9 * * Mon" für Erinnerung

Montag, 9 Uhr:
  - System sendet Erinnerung: "Neue Events verfügbar!"
  - Mitarbeiter sehen neu veröffentlichte Events

Szenario 2: Kurzfristige Änderungen

Mittwoch, 14:30:
  - Admin aktualisiert Event (Type: "direct")

Sofort:
  - Push-Benachrichtigungen gehen raus
  - E-Mails ebenfalls (für die, die E-Mail AN haben)

Szenario 3: Verfügbarkeitseingabe

Mitarbeiter hat für nächste Woche keine Verfügbarkeit eingegeben.
Freitag, 17 Uhr:
  - Cron-Trigger "availabilityReminder" mit Pattern "0 17 * * 5" (Freitag 17 Uhr)
  - System sendet: "Gib bitte deine Verfügbarkeit für nächste Woche ein"

Häufige Konfigurationsbeispiele

Szenario A: Casual, flexibler Betrieb

Availability Reminder: Aus (keine Verfügbarkeit erforderlich)
Assignment Reminder: Aus (Mitarbeiter schauen selbst im Kalender)
Published Events: "direct" (sofort, wenn Admin Events veröffentlicht)

Effekt: Minimal automatisierte Benachrichtigungen,
        aber Events werden sofort kommuniziert.

Szenario B: Strukturierter Betrieb

Availability Reminder: An, Pattern: "0 17 * * 4" (Donnerstag 17 Uhr)
Assignment Reminder: An, Pattern: "0 9 * * 0" (Sonntag 9 Uhr)
Published Events: "scheduled", Pattern: "0 18 * * *" (täglich 18 Uhr)

Effekt: Regelmäßige, vorhersehbare Benachrichtigungsfluten.
        Mitarbeiter wissen: Donnerstag 17 Uhr → Verfügbarkeit, Sonntag 9 Uhr → Schichten

Szenario C: Events-last-minute (Eventmanagement)

Availability Reminder: Aus (Events sind meist ad-hoc)
Assignment Reminder: Aus (Event-spezifisch, Mitarbeiter wissen Bescheid)
Published Events: "direct" (sofort informieren wenn Event live geht)

Effekt: Sofortige Benachrichtigungen bei Event-Veröffentlichung.

Troubleshooting

Problem: Mitarbeiter erhalten gar keine Benachrichtigungen Mögliche Ursachen:

1. Team-Trigger ist AUS (Check Admin Settings > Notifications)
2. Mitarbeiter hat diese Benachrichtigung in seinen Preferences AUS
3. User-Preferences wurden nicht gespeichert

Lösung:

1. Check das entsprechende Team-Trigger-Setting
2. Bitte Mitarbeiter, seine Preferences zu überprüfen
3. Teste mit einem Test-Event

Problem: Zu viele Benachrichtigungen Mögliche Ursachen:

1. Trigger-Pattern sendet zu oft (z.B. alle 30 Minuten statt täglich)
2. Mehrere Trigger-Typen sind gleichzeitig aktiviert

Lösung:

1. Ändere Cron-Pattern auf ein sinnvolleres Intervall
2. Überlege, welche Trigger wirklich nötig sind

For Developers

System Architecture

Notifications sind in zwei Teile aufgesplittet:

1. Trigger-Configuration (Team-Level)

• Stored in DBTeam table:

  • availabilityReminderEnabled (boolean)
  • availabilityReminderMessagePattern (cron string)
  • assignmentReminderEnabled (boolean)
  • assignmentReminderMessagePattern (cron string)
  • publishedEventsMessageEnabled (boolean)
  • publishedEventsMessageType ('direct' | 'scheduled')
  • publishedEventsMessagePattern (cron string, nullable)

• Implementation: src/sections/teams/edit-form/notifications.tsx

2. User-Preferences (User-Level)

• Stored in DBUserNotification table (user membership settings)
• Record: { userId: number, teamId: number, notificationType: DBUserNotification, email: boolean, push: boolean }
• Implementation: src/sections/account/account-notifications.tsx

Available Notification Types

All defined in _types/enums.ts:

export enum DBUserNotification {
    EVENT_PUBLISHED = 'event-published',
    AVAILABILITIES_REMINDER = 'availabilities-reminder',
    SCHEDULE_CREATED = 'schedule-created',
    SCHEDULE_UPDATED = 'schedule-updated',
    ASSIGNMENTS_REMINDER = 'assignments-reminder',
    ASSIGNMENT_CANCELED_BY_ADMIN = 'assignment-canceled-by-admin',
    ADMIN_ASSIGNMENT_CANCELED = 'admin-assignment-canceled',
    EMPLOYEE_SELF_CANCELED = 'employee-self-canceled',
    POSITION_DELETED = 'position-deleted',
}

Push-Only Notifications

Some notifications are push-only (no email option):

const PUSH_ONLY_NOTIFICATIONS = new Set<DBUserNotification>([
    DBUserNotification.ADMIN_ASSIGNMENT_CANCELED,
]);

Logic in src/sections/account/account-notifications.tsx:

• These types have pushOnly: true in the UI
• Email channel is hidden/forced to false
• normalizeNotifications() function enforces email: false for these types

Default Notification Settings

Built from enum via getDefaultNotifications() in account-notifications.tsx:

const notificationDefaults: Partial<Record<DBUserNotification, { email: boolean; push: boolean }>> =
    {
        [DBUserNotification.EVENT_PUBLISHED]: { email: true, push: true },
        [DBUserNotification.SCHEDULE_CREATED]: { email: true, push: true },
        [DBUserNotification.SCHEDULE_UPDATED]: { email: true, push: true },
        [DBUserNotification.ASSIGNMENTS_REMINDER]: { email: true, push: true },
        [DBUserNotification.AVAILABILITIES_REMINDER]: { email: true, push: true },
        [DBUserNotification.ASSIGNMENT_CANCELED_BY_ADMIN]: { email: true, push: true },
        [DBUserNotification.ADMIN_ASSIGNMENT_CANCELED]: { email: false, push: true },
        [DBUserNotification.EMPLOYEE_SELF_CANCELED]: { email: true, push: true },
        [DBUserNotification.POSITION_DELETED]: { email: true, push: true },
    };

Team Availability Dependency

Availability reminder is only relevant if availabilitiesEnabled = true:

From src/sections/teams/edit-form/notifications.tsx:

{availabilitiesEnabled && availabilityReminderEnabled && (
    // Show cron pattern field for availability reminder
)}

Conditional rendering ensures UX clarity.

Cron Pattern Implementation

Uses standard cron syntax (5-field format):

* * * * *
│ │ │ │ └─ Day of Week (0-6)
│ │ │ └─── Month (1-12)
│ │ └───── Day of Month (1-31)
│ └─────── Hour (0-23)
└───────── Minute (0-59)

Examples:

• 0 9 * * 1 = Every Monday at 9:00 AM
• 0 18 * * * = Every day at 6:00 PM
• 0 9 1 * * = First day of month at 9:00 AM

Backend processes these via BullMQ queue with node-cron or similar for job scheduling.

Message Sending Flow

Direct type:

Event Published by Admin
→ Backend triggers notification immediately
→ Sends to all users with EVENT_PUBLISHED preference enabled
→ Respects email/push channel preference

Scheduled type:

Events published throughout the day
→ Cron job runs at scheduled time
→ Collects all new events since last run
→ Sends batch notification
→ Respects user preferences per event type

User Preferences Update

Endpoint: updateUserMembershipNotifications() in src/lib/axios/user-memberships.ts

• Payload: Record of notification type → {email, push} settings
• Validation: Enforces push-only constraint during normalization
• Response: Updated user membership preferences

Integration Points

• Events Module: When event is published/updated, check trigger type and send notifications
• Schedule Module: When schedule is created/updated, send notifications
• User Memberships: Store and retrieve notification preferences per user per team
• BullMQ Queues: Background job for cron-triggered reminders
• Email/Push Services: Actually send the messages (via Email service + Service Worker for push)