at_zeiterfassung – Anwender- und Administrator-Handbuch

Version 1.1.0 · Redmine 5.1 und 6 · GPLv2

Dieses Handbuch beschreibt Installation, Konfiguration und täglichen Einsatz des atori-Zeiterfassungs-Plugins.

1. Überblick

Das Plugin ergänzt Redmine um ein wochenbasiertes Stundenraster mit Raster-Eingabe, einen laufenden Timer, eine Monatsansicht und einen zweistufigen Genehmigungsworkflow – aufbauend auf dem Standard- TimeEntry-Modell von Redmine. Es gibt keine parallele Zeit-Datenbank, keine Schattendaten: Eingaben hier werden als reguläre Redmine-Zeiteinträge gespeichert und erscheinen in den üblichen Reports, Ticket-Ansichten und über die API.

Zentrale Begriffe:

Wochengrid – eine Zeile pro Ticket, eine Spalte pro Wochentag. In jeder Zelle können ein oder mehrere Einträge für die Kombination Tag / Ticket stehen.
Timer – wird auf einem Ticket gestartet, läuft im Hintergrund, stoppt als TimeEntry auf dem heutigen Tag.
Favoriten-Tickets – benutzerspezifische Shortcut-Liste, damit häufig benutzte Tickets oben im Picker erscheinen.
Wochen-Submission – Datensatz, dass ein Benutzer die Woche eines bestimmten Startdatums zur Freigabe eingereicht hat. Kann in einem von drei Zuständen sein: eingereicht, genehmigt, abgelehnt.
Sperre – eingereichte und genehmigte Wochen sind gesperrt: keine Zeiteinträge können hinzugefügt, geändert oder gelöscht werden, bis die Woche wieder geöffnet ist.

2. Voraussetzungen

Redmine 5.1.0 oder neuer
Ruby 3.0 oder neuer
Keine zusätzlichen Gems, keine externen Services

3. Installation

Aus einem Release-Archiv

cd /pfad/zu/redmine
unzip at_zeiterfassung-1.4.0.zip -d plugins/
bundle exec rake redmine:plugins:migrate NAME=at_zeiterfassung RAILS_ENV=production
# Redmine neu starten

Aus einem Git-Checkout

cd /pfad/zu/redmine
git clone <repo-url> plugins/at_zeiterfassung
bundle exec rake redmine:plugins:migrate NAME=at_zeiterfassung RAILS_ENV=production
# Redmine neu starten

Installation prüfen

Als Administrator einloggen und Administration → Plugins öffnen. Das Plugin Zeiterfassung sollte mit Version 1.1.0 erscheinen. In der oberen Navigation sollte für Benutzer mit dem Recht Eigene Zeiterfassung ansehen der Eintrag Zeiterfassung auftauchen.

Deinstallation

cd /pfad/zu/redmine
bundle exec rake redmine:plugins:migrate NAME=at_zeiterfassung VERSION=0 RAILS_ENV=production
rm -rf plugins/at_zeiterfassung
# Redmine neu starten

Der Rake-Task entfernt die Plugin-Tabellen (Timer, Favoriten, Wochen-Submissions). Die über das Plugin geschriebenen Redmine-TimeEntry-Daten bleiben erhalten und funktionieren weiterhin im Standard-UI.

4. Konfiguration

4.1 Plugin-Einstellungen

Unter Administration → Plugins → Zeiterfassung → Konfigurieren:

Einstellung	Zweck	Standard
Tägliche Sollstunden	Referenzwert für Tages-/Wochensummen-Einfärbung	8.0
Arbeitstage	Wochentage, die als Arbeitstage gelten	Mo–Fr
Zukünftige Einträge zulassen	Ob Zeit für Daten nach heute erfasst werden darf	nein
Eingereichte Wochen sperren	Ob eingereichte/genehmigte Wochen schreibgeschützt sind	ja
Standard-Tätigkeit	Vorausgewählte Tätigkeit bei neuen Einträgen	—

4.2 Berechtigungen vergeben

Zwei unabhängige globale Rechte stehen unter Administration → Rollen und Rechte → Zeiterfassung zur Verfügung:

Recht	Wirkung	Typische Rolle
Eigene Zeiterfassung ansehen	Nutzung von Wochengrid, Timer, Favoriten; Wochen einreichen	Jeder Benutzer
Zeiterfassung genehmigen	Offene Submissions sehen, genehmigen / ablehnen / wieder öffnen	Projektleitung

Beide Rechte sind global (nicht projektbezogen), weil das Stundenblatt sich über alle Projekte erstreckt, zu denen der Benutzer Zugriff hat.

5. Bedienung

5.1 Stundenblatt öffnen

Zeiterfassung in der oberen Navigation öffnet die aktuelle Woche. Linke Seite: Wochengrid. Rechte Seite: Timer und Favoritenliste.

5.2 Zeit im Grid erfassen

In die Zelle für die gewünschte Kombination Tag / Ticket klicken, Stunden eingeben, mit Enter bestätigen. Der Eintrag wird als TimeEntry geschrieben, Tages- und Wochensumme aktualisieren sich ohne Seitenneuladen.

Für eine neue Ticketzeile die Eintrag hinzufügen-Suche am unteren Ende des Grids verwenden. Ticket-ID eingeben oder per Betreff suchen. Tätigkeit und Kommentar sind direkt in der Zeile editierbar.

5.3 Der Timer

Im Timer-Panel rechts eine Ticket-ID oder einen Suchbegriff eingeben, optional einen Kommentar, und Timer starten klicken. Der Timer läuft im Hintergrund weiter, auch über Logouts hinweg (Zustand wird serverseitig gespeichert).

Timer stoppen schreibt einen TimeEntry auf den heutigen Tag mit der verstrichenen Zeit und setzt den Timer zurück. Ein laufender Timer lässt sich auch ohne Eintrag verwerfen.

5.4 Favoriten

Ein Ticket im Grid mit dem Stern markieren, um es zur Favoritenliste hinzuzufügen. Favoriten erscheinen oben im Ticket-Picker, sowohl im Grid als auch im Timer. Stern erneut klicken zum Entfernen. Favoriten sind benutzerspezifisch; die Liste eines Benutzers beeinflusst keine andere.

5.5 Vorwoche kopieren

Vorwoche kopieren dupliziert die Struktur der vorangegangenen Woche (Tickets und Tätigkeiten) mit Null-Stunden in die aktuelle Woche. Praktisch für Teams, die regelmäßig an derselben Ticketmenge arbeiten und nur die Mengen ausfüllen müssen.

5.6 Monatsansicht

Zwischen Woche und Monat über den Ansichtsumschalter wechseln. Die Monatsansicht zeigt eine kompakte Tagesübersicht über alle Wochen des gewählten Monats. Praktisch für Reporting und Plausibilitätsprüfungen; editiert wird weiterhin im Wochengrid.

Der gewählte Zeitraum (Woche/Monat) und Darstellungsmodus (kompakt/Blöcke) werden pro Benutzer gemerkt. Ein erneuter Aufruf der Zeiterfassung ohne explizite Query-Parameter öffnet die zuletzt verwendete Ansicht.

5.7 Woche einreichen

Wenn die Woche komplett ist, Woche einreichen klicken. Der Zustand wechselt auf eingereicht, die Woche wird gegen weitere Änderungen gesperrt (sofern Eingereichte Wochen sperren aktiv ist), und Genehmiger sehen die Submission unter Genehmigungen.

5.8 Genehmigungs-Workflow

Benutzer mit dem Recht Zeiterfassung genehmigen öffnen Zeiterfassung → Genehmigungen, um offene Submissions zu sehen. Pro Submission stehen zur Verfügung:

Genehmigen – Woche geht in den Zustand genehmigt, bleibt gesperrt.
Ablehnen – Woche geht in den Zustand abgelehnt, wird wieder editierbar, der Einreichende kann nachbessern und erneut einreichen.
Wiedereröffnen (nach Genehmigung) – Woche wird erneut editierbar. Sparsam nutzen; Wiedereröffnungen sollten nachvollziehbare Ereignisse sein – sind sie, über die Felder updated_at und reviewer_id der Submission.

6. Troubleshooting

Zeiterfassung nicht im oberen Menü. Der Benutzer benötigt das Recht Eigene Zeiterfassung ansehen in mindestens einer Rolle. Unter Administration → Rollen und Rechte zuweisen.

Einträge lassen sich nicht hinzufügen – Woche scheint gesperrt. Zustand der Wochen-Submission unter Genehmigungen (für Genehmiger) oder das Status-Panel auf der Woche (für Benutzer) prüfen. Eine eingereichte oder genehmigte Woche ist per Design schreibgeschützt. Ein Genehmiger muss die Submission ablehnen oder wiedereröffnen, damit das Editieren wieder möglich ist.

Timer stoppt nicht / hängt. Seite neu laden. Der Timer-Zustand liegt serverseitig; ein Browser- Hänger ist kosmetisch. In seltenen Fällen (z.B. abgestürzter Browser beim Start) den Timer aus dem Timer-Panel verwerfen und einen neuen starten.

Favoriten bleiben nicht erhalten. Favoriten sind benutzerspezifisch. Sicherstellen, dass man als der gewünschte Benutzer eingeloggt ist, nicht als gemeinsam genutzter Demo-Account.

Einträge erscheinen in Redmine-Reports, aber nicht im Grid. Das Grid zeigt Einträge innerhalb der für den Benutzer sichtbaren Projekte für die aktuelle Woche. Woche (obere Navigation) und Projektmitgliedschaft des Benutzers gegenprüfen.

7. Support

Support ist für zwölf Monate ab Kaufdatum enthalten.

E-Mail: support@atori.de Erstreaktion: werktags innerhalb von 48 Stunden.

Bitte in Supportanfragen angeben:

Redmine-Version (z.B. 5.1.5 oder 6.1.2)
Plugin-Version (sichtbar unter Administration → Plugins)
Browser und Browserversion
Schritte zur Reproduktion und das beobachtete Verhalten
Relevante Zeilen aus log/production.log, sofern verfügbar