Zum Inhalt

Onboarding Modul

Zweck

Das Onboarding Modul bietet eine interaktive Einführung in TimeAM für neue Benutzer. Es führt schrittweise durch die wichtigsten Funktionen und hilft, die Anwendung schnell und effektiv zu nutzen.

Verantwortlichkeiten

Was gehört zum Modul

  • Core-Onboarding: Einführung in grundlegende Funktionen (Dashboard, Kalender, Mitarbeiter)
  • Modul-Onboardings: Spezifische Einführungen für einzelne Module
  • Interaktive Tours: Schritt-für-Schritt-Anleitungen mit Overlays
  • Progress-Tracking: Speicherung des Onboarding-Fortschritts
  • Hilfe-Button (FAB): Floating Action Button für schnellen Zugriff auf Hilfe

Was gehört nicht zum Modul

  • User-Support: Siehe Helpdesk-Modul
  • Dokumentation: Siehe FAQ und Benutzerhandbücher

Implementierung

Backend- und Frontend-API sind modular aufgebaut; Details siehe interne Entwickler-Dokumentation.

Konfiguration

Entitlement

Das Onboarding-System ist für alle Benutzer verfügbar (Core-Funktionalität).

Kein Entitlement erforderlich – Verfügbar in allen Plänen.

Defaults

  • Core-Onboarding: Startet automatisch bei Erstanmeldung
  • Modul-Onboardings: Starten beim ersten Besuch der Modul-Seite
  • FAB-Button: Immer sichtbar (kann minimiert werden)

API-Endpunkte

Alle Endpoints erfordern Authentifizierung.

Base URL: /api/onboarding

Onboarding-Status abrufen

GET /api/onboarding/status

Lädt den aktuellen Onboarding-Status des Benutzers.

Response: 

{
  "status": {
    "coreCompleted": false,
    "moduleCompleted": {
      "time-tracking": true,
      "shift-pool": false,
      "projects": false
    },
    "fabDismissed": false,
    "lastUpdated": "2026-01-04T10:30:00Z"
  }
}

Core-Onboarding abschließen

POST /api/onboarding/complete/core

Markiert das Core-Onboarding als abgeschlossen.

Response: 

{
  "status": {
    "coreCompleted": true,
    "moduleCompleted": {},
    "fabDismissed": false,
    "lastUpdated": "2026-01-04T10:35:00Z"
  }
}

Modul-Onboarding abschließen

POST /api/onboarding/complete/module/:moduleId

Markiert das Onboarding für ein spezifisches Modul als abgeschlossen.

URL-Parameter: - moduleId: ID des Moduls (z.B. time-tracking, shift-pool)

Response: 

{
  "status": {
    "coreCompleted": true,
    "moduleCompleted": {
      "time-tracking": true
    },
    "fabDismissed": false,
    "lastUpdated": "2026-01-04T10:40:00Z"
  }
}

Onboarding zurücksetzen

POST /api/onboarding/reset

Setzt Onboarding-Status zurück (zum erneuten Durchlaufen).

Request Body: 

{
  "type": "core" | "module" | "all",
  "moduleId": "time-tracking"  // Nur bei type: "module"
}

Response: 

{
  "status": {
    "coreCompleted": false,
    "moduleCompleted": {},
    "fabDismissed": false,
    "lastUpdated": "2026-01-04T10:45:00Z"
  }
}

FAB-Button ausblenden

POST /api/onboarding/dismiss-fab

Markiert den Floating Action Button als ausgeblendet.

Response: 

{
  "status": {
    "coreCompleted": true,
    "moduleCompleted": {},
    "fabDismissed": true,
    "lastUpdated": "2026-01-04T10:50:00Z"
  }
}

Status-Codes

  • 200 OK: Erfolgreich
  • 400 Bad Request: Ungültige Anfrage
  • 401 Unauthorized: Nicht authentifiziert
  • 404 Not Found: Modul nicht gefunden
  • 500 Internal Server Error: Server-Fehler

Fehlercodes

  • VALIDATION_ERROR: Ungültiger Anfrage-Body
  • MODULE_NOT_FOUND: Modul-ID existiert nicht

Features

Core-Onboarding

Grundlegende Einführung für alle neuen Benutzer:

Abgedeckte Bereiche: 1. Dashboard: Übersicht und wichtigste Metriken 2. Kalender: Terminansicht und Navigation 3. Mitarbeiter: Team-Übersicht 4. Navigation: Menüstruktur und Module 5. Profil: Einstellungen und Benutzer-Profil

Ablauf: - Startet automatisch beim ersten Login - Interaktive Overlays mit Erklärungen - "Weiter"-Button zum Fortfahren - "Überspringen"-Option verfügbar - Progress-Anzeige (Schritt X von Y)

Modul-spezifische Onboardings

Jedes Modul kann ein eigenes Onboarding haben:

Verfügbare Module: - ⏱️ Zeiterfassung: Timer starten/stoppen, manuelle Eingabe - 📆 Schichtplanung: Schichten ansehen, bewerben, tauschen - 📁 Projekte: Projekt erstellen, Zeit buchen - 💰 Rechnungen: Rechnung erstellen, exportieren - 🎫 Helpdesk: Ticket erstellen, Status prüfen - 🎨 Branding: Custom Branding konfigurieren

Ablauf: - Startet beim ersten Besuch der Modul-Seite - Nur verfügbar, wenn Core-Onboarding abgeschlossen - Modul-spezifische Erklärungen - Praktische Beispiele

Floating Action Button (FAB)

Permanenter Hilfe-Button in der rechten unteren Ecke:

Features: - Immer verfügbar: Schneller Zugriff auf Hilfe - Menü-Optionen: - Support kontaktieren - Onboarding wiederholen - FAQ aufrufen - Abonnement verwalten (Admin/Manager) - Minimierbar: Kann ausgeblendet werden - Wiederaufrufbar: Jederzeit wieder einblendbar

Intelligentes Triggering

Onboardings starten automatisch zur richtigen Zeit: - Core: Beim ersten Login - Module: Beim ersten Besuch (nach Core-Completion) - URL-Parameter: Manueller Start via ?onboarding=module-id - Rollenbasiert: Unterschiedliche Inhalte für Admin/Manager/Mitarbeiter

Progress-Tracking

Vollständige Nachverfolgung des Fortschritts: - Welche Onboardings wurden abgeschlossen? - Wann wurde ein Onboarding zuletzt durchlaufen? - Kann jederzeit zurückgesetzt werden

Onboarding-Struktur

OnboardingStep-Format

Jeder Schritt hat folgende Eigenschaften:

interface OnboardingStep {
  selector: string;        // CSS-Selector des Elements
  title: string;          // Titel des Overlays
  content: string;        // Erklärungstext
  position?: 'top' | 'bottom' | 'left' | 'right';  // Position des Overlays
  action?: 'click' | 'hover';  // Erforderliche Aktion
}

Beispiel: 

{
  selector: '[data-tour="dashboard-stats"]',
  title: 'Dashboard-Statistiken',
  content: 'Hier sehen Sie die wichtigsten Kennzahlen auf einen Blick.',
  position: 'bottom'
}

Onboarding-Registry

Zentrale Registrierung aller verfügbaren Onboardings:

interface OnboardingDefinition {
  moduleId: string;
  displayName: string;
  route: string;
  steps: OnboardingStep[];
  requiredRole?: ('admin' | 'manager' | 'employee')[];
}

Beispiel: 

{
  moduleId: 'time-tracking',
  displayName: 'Zeiterfassung',
  route: '/time-tracking',
  steps: [/* ... */],
  requiredRole: ['admin', 'manager', 'employee']
}

Best Practices

Für Entwickler (Neues Onboarding erstellen)

  1. Selektoren verwenden: Nutzen Sie data-tour="..." Attribute
  2. Kurze Texte: Maximal 2-3 Sätze pro Schritt
  3. Logische Reihenfolge: Von wichtig zu unwichtig
  4. Testing: Testen Sie alle Schritte in verschiedenen Rollen
  5. Responsive Design: Onboarding muss auch mobil funktionieren

Für Benutzer

  • Core-Onboarding: Nicht überspringen – spart später Zeit
  • Modul-Onboardings: Kurze Einführungen, sehr hilfreich
  • FAB-Button: Nutzen Sie ihn bei Fragen
  • Wiederholen: Onboardings können jederzeit wiederholt werden

Für Administratoren

  • Neue Mitarbeiter: Empfehlen Sie das Core-Onboarding
  • Schulungen: Nutzen Sie Onboardings als Schulungs-Tool
  • Feedback: Sammeln Sie Feedback zum Onboarding-Inhalt

Integration in neue Module

Um ein Onboarding für ein neues Modul zu erstellen:

  1. Schritte definieren: Liste der OnboardingSteps erstellen
  2. In Registry eintragen: OnboardingDefinition hinzufügen
  3. Data-Attribute: data-tour zu relevanten Elementen hinzufügen
  4. Testen: Onboarding im Modul durchlaufen

Troubleshooting

Onboarding startet nicht

  • Lösung 1: Prüfen Sie, ob Core-Onboarding abgeschlossen ist
  • Lösung 2: Laden Sie die Seite neu
  • Lösung 3: Starten Sie manuell über FAB-Button

Schritte werden nicht angezeigt

  • Lösung 1: Element ist nicht sichtbar/verfügbar
  • Lösung 2: CSS-Selector stimmt nicht
  • Lösung 3: Berechtigung fehlt für das Feature

FAB-Button fehlt

  • Lösung 1: Wurde ausgeblendet – per URL-Parameter wieder einblenden
  • Lösung 2: JavaScript-Fehler – Console prüfen
  • Lösung 3: Ad-Blocker deaktivieren

FAQ

Kann ich das Onboarding überspringen?

Ja, jedes Onboarding kann übersprungen werden. Wir empfehlen jedoch, zumindest das Core-Onboarding durchzulaufen.

Kann ich Onboardings wiederholen?

Ja, über den FAB-Button oder die Einstellungen können Sie jedes Onboarding erneut starten.

Gibt es Onboardings für alle Module?

Die meisten Module haben ein Onboarding. Neue Module erhalten nach und nach Onboardings.

Kann ich als Admin Onboardings für Mitarbeiter zurücksetzen?

Nein, jeder Benutzer verwaltet seinen eigenen Onboarding-Status. Empfehlen Sie neuen Mitarbeitern, das Onboarding durchzulaufen.

Siehe auch