Resource Planning Calendar – Dokumentation

Der Resource Planning Calendar ermöglicht intuitive Drag-&-Drop Ressourcenplanung direkt in Matrix42. Schichten, Fahrzeuge, Räume oder beliebige andere Ressourcen lassen sich in einer übersichtlichen Kalenderansicht verwalten.

Funktionsumfang

Architektur

Die Extension wird als Front-End Workspace in Matrix42 integriert. Das AngularJS-Modul RootITUp.PlanningCalendar nutzt Angular Material für Dialoge und Tippy.js für Tooltips.

Komponenten

Genutzte Matrix42-Services

• mx.sb.public.service – Benachrichtigungen (Success/Error)
• mx.SolutionBuilderAgent.DataService – CRUD-Operationen für Zuweisungen

API-Berechtigungen

Der Kalender nutzt die öffentliche Matrix42 REST-API zum Speichern von Zuweisungen:

Wichtig: Diese API ist standardmäßig auf Administratoren beschränkt. Für den produktiven Einsatz muss die Berechtigung explizit an die gewünschte Benutzergruppe vergeben werden (z. B. über Rollen oder Berechtigungsgruppen in der Matrix42 Administration).

Abhängigkeiten

Das Modul lädt automatisch:

• Tippy.js – Dynamische Tooltips mit HTML-Inhalt
• Angular Material – Dialoge und Formularelemente

Installation

Extension Gallery

1. Matrix42 Administration öffnen
2. Zu Administration → Extensions → Extension Gallery navigieren
3. Nach „Resource Planning Calendar” von RootITUp suchen
4. Auf „Install” klicken und warten, bis die Installation abgeschlossen ist

Voraussetzung: Administrative Rechte im Matrix42-System.

Basiskonfiguration

1. Layout erstellen

Im Layout Builder ein neues Widget-Layout oder eine Page erstellen, auf der die Ressourcenplanung angezeigt werden soll.

2. Kalender einfügen

1. In der Toolbox nach „Planning” suchen
2. Das Element „Resource Planning Calendar” per Drag-&-Drop platzieren

3. Pflichtfelder konfigurieren

Der Kalender benötigt mindestens drei Eingaben:

Datenmodell

Items (Zeilen)

Jede Zeile repräsentiert eine planbare Ressource:

const items = [
  {
    id: "ec4369f1-7431-4bd0-9277-20c5b32a57f3",
    title: "Max Mustermann",
    description: "Teamleitung" // optional
  },
  {
    id: "bd967992-1e66-4cea-b711-570f41c6b678",
    title: "Dienstwagen A-XY 123",
    description: "VW Golf"
  }
];

Choices (Zuweisungsoptionen)

Jede Option definiert, was zugewiesen werden kann. Die id sollte die Expression Object ID des Zielobjekts sein (siehe resultType).

Wiederverwendbare Callback-Funktion

Für mehrere Choices mit gleichem Speicherformat empfiehlt sich eine zentrale Callback-Funktion:

function mapToObject(item, choice, startDate, endDate, notes) {
  return {
    mP_TimeRecordClass: {
      mP_Approved: 1,
      mP_CreatedManually: 1,
      mP_FullTimeAbsence: 0,
      mP_HalfDayAbsence: 0,
      mP_NoPauseTaken: 1,
      mP_RecordStarted: 0,
      mP_RecordStopped: 1,
      mP_RecordWasNotStopped: 0,
      mP_SmokingBreak: 0,
      mP_Minutes: choice.custom.minutes, // Aus custom-Eigenschaft
      mP_StartDate: startDate,
    },
  };
}

Farbpalette

const shiftColors = [
  "#4A90E2", "#50E3C2", "#F5A623", "#BD10E0",
  "#9013FE", "#B8E986", "#7ED321", "#F8E71C",
];

Vollständiges Beispiel

const choices = [
  {
    // Expression Object ID der Choice
    id: "f852ce66-9b0b-4e4e-9870-0d811ffe21bd",
    title: "FR6",
    description: "Frühschicht 6",
    start: "07:00",
    end: "14:00",
    color: shiftColors[0],
    icon: "wb_sunny",
    result: mapToObject,
    resultType: "mP_TimeRecordType",
    // Custom-Attribute für die Callback-Funktion
    custom: {
      minutes: 375, // 6 Stunden 15 Minuten
    },
  },
  {
    id: "b1c2d3e4-f5a6-7b8c-9d0e-f1a2b3c4d5e6",
    title: "SP",
    description: "Spät",
    start: "13:30",
    end: "22:00",
    color: shiftColors[1],
    icon: "brightness_3",
    result: mapToObject,
    resultType: "mP_TimeRecordType",
    custom: {
      minutes: 510, // 8 Stunden 30 Minuten
    },
  },
  {
    id: "c7d8e9f0-a1b2-c3d4-e5f6-7890abcdef12",
    title: "URL",
    description: "Urlaub",
    start: "08:00",
    end: "16:00",
    color: shiftColors[2],
    icon: "beach_access",
    result: mapToObject,
    resultType: "mP_TimeRecordType",
    custom: { minutes: 480 },
    isSelectable: false, // Nur Anzeige, nicht auswählbar
  },
  {
    id: "d1e2f3a4-b5c6-d7e8-f9a0-b1c2d3e4f5a6",
    title: "KRANK",
    description: "Krankheit",
    start: "08:00",
    end: "16:00",
    color: shiftColors[3],
    icon: "local_hospital",
    result: mapToObject,
    resultType: "mP_TimeRecordType",
    custom: { minutes: 480 },
    isSelectable: false,
    isRelevantForTotals: false, // Nicht in Arbeitsstunden-Summe
  },
];

Pflichtfelder für Choices

Optionale Felder

Existing Assignments (Bestehende Zuweisungen)

Zum Laden bereits gespeicherter Daten:

const existingAssignments = [
  {
    objectId: "12345-abcde-67890",
    itemId: "ec4369f1-7431-4bd0-9277-20c5b32a57f3",
    choiceId: "shift-early-01",
    type: "MyExtension_ShiftAssignmentType",
    start: "2026-02-15T07:00:00Z",
    end: "2026-02-15T13:00:00Z",
    notes: "Vertretung für Team B",
    isModifiable: true
  }
];

Background Assignments (Hintergrundmarkierungen)

Für Feiertage, Urlaub oder andere Hintergrundinformationen:

const backgroundAssignments = [
  {
    itemId: "ec4369f1-7431-4bd0-9277-20c5b32a57f3",
    date: "2026-02-14",
    color: "#FF9800",
    title: "Urlaub",
    shortTitle: "U",
    icon: "beach_access"
  }
];

Hintergründe werden unabhängig von regulären Zuweisungen angezeigt und nehmen nicht an der Überschneidungsprüfung teil.

Zielstunden-Tracking

Targets konfigurieren

Über das targets-Array lassen sich Soll-Stunden pro Element definieren:

const targets = [
  {
    itemId: "ec4369f1-7431-4bd0-9277-20c5b32a57f3",
    target: {
      type: "month", // oder "week"
      hours: 160
    },
    validFrom: "2026-01-01", // optional
    validTo: "2026-12-31",   // optional
    successPercentage: 80    // optional, Standard: 70
  }
];

Skalierung

Wird ein Wochen-Ziel in der Monatsansicht angezeigt (oder umgekehrt), skaliert der Kalender automatisch:

Fortschrittsbalken-Farben

Die Farben des Fortschrittsbalkens sind konfigurierbar:

Position der Total-Spalte

Die Spalte mit dem Fortschrittsbalken lässt sich links oder rechts positionieren:

<rootitup-planning-calendar
  total-column-position="left">
</rootitup-planning-calendar>

Saldo-Anzeige

Über das balances-Array lassen sich Übertragswerte aus Vormonaten anzeigen:

const balances = [
  {
    itemId: "ec4369f1-7431-4bd0-9277-20c5b32a57f3",
    month: "2026-01", // Format YYYY-MM
    minutes: -120     // negativ = Minusstunden
  }
];

Der Saldo wird in den zwei Folgemonaten nach dem angegebenen Monat angezeigt.

Zusammenfassungszeilen

Mit dem summaries-Array lassen sich aggregierte Zeilen am unteren Rand konfigurieren:

const summaries = [
  {
    title: "Arbeitsstunden gesamt",
    icon: "schedule",
    iconColor: "#4CAF50",
    choiceIds: ["shift-early-01", "shift-late-01", "shift-night-01"],
    emptyText: "Keine Schichten geplant"
  }
];

Die Zusammenfassung summiert die Dauer aller Zuweisungen, deren choiceId im Array enthalten ist.

Benutzerinteraktion

Neue Zuweisung erstellen

1. Zellen auswählen: Mit gedrückter Maustaste über den gewünschten Datumsbereich ziehen
2. Dialog öffnet sich: Verfügbare Optionen werden angezeigt
3. Option auswählen: Zeiten können angepasst werden
4. Speichern: Die Zuweisung wird erstellt und optimistisch angezeigt

Bestehende Zuweisung bearbeiten

1. Auf Chip klicken: Der Bearbeitungsdialog öffnet sich
2. Zeiten anpassen: Start- und Endzeit können geändert werden
3. Notizen hinzufügen: Freitext-Feld für zusätzliche Informationen
4. Speichern oder Löschen: Änderungen werden übernommen

Zuweisungen löschen

Im Auswahldialog (Bereichsauswahl) steht die Option „Alle Zuweisungen löschen” zur Verfügung. Diese entfernt alle bearbeitbaren Zuweisungen im ausgewählten Bereich nach Bestätigung.

Überschneidungserkennung

Der Kalender prüft automatisch auf Zeitkonflikte:

• Beim Erstellen: Neue Zuweisungen werden abgelehnt, wenn sie sich mit bestehenden überschneiden
• Beim Bearbeiten: Geänderte Zeiten werden gegen andere Zuweisungen im selben Slot geprüft
• Hintergründe ausgenommen: Background Assignments nehmen nicht an der Prüfung teil

Schreibschutz

Der gesamte Kalender lässt sich in den Nur-Lesen-Modus versetzen:

<rootitup-planning-calendar
  is-read-only="true">
</rootitup-planning-calendar>

Im Schreibschutzmodus sind keine Interaktionen möglich – ideal für Reporting-Ansichten.

Optimistische Updates

Alle Datenbankoperationen verwenden optimistische Updates:

1. Die UI wird sofort aktualisiert
2. Die API-Anfrage wird im Hintergrund ausgeführt
3. Bei Fehler wird der vorherige Zustand wiederhergestellt

Dies sorgt für eine reaktive Benutzererfahrung ohne wahrnehmbare Wartezeiten.

Ansichten

Monatsansicht

Standard-Ansicht mit allen Tagen des Monats. Jeder Tag zeigt:

• Zuweisungs-Chips
• Hintergrundfarben (falls konfiguriert)
• Wochennummer in der Navigation

Wochenansicht

Kompakte 7-Tage-Ansicht der aktuellen Woche. Ideal für detaillierte Tagesplanung.

Jahresansicht

Kompakte Übersicht aller 12 Monate. Jeder Tag wird als farbiger Punkt dargestellt:

• Farbe der ersten Zuweisung oder des Hintergrunds
• Tooltip zeigt alle Zuweisungen
• Klick öffnet die Monatsansicht

Barrierefreiheit

Die Tooltips nutzen Tippy.js mit folgendem Setup:

tippy(element, {
  allowHTML: true,
  theme: "custom-dark",
  animation: "fade"
});

Alle Interaktionen sind tastaturzugänglich über Angular Material Dialoge.

Changelog

Häufig gestellte Fragen