Version 1.7.0 · Redmine 5.1 und 6 · GPLv2
Dieses Handbuch beschreibt Installation, Konfiguration und täglichen Einsatz des atori-Zeiterfassungs-Plugins.
Das Plugin ergänzt Redmine um ein wochenbasiertes Stundenraster mit Raster-Eingabe, mehrere parallele Timer, eine Monatsansicht, einen zweistufigen Genehmigungsworkflow und ein projektbezogenes Aufwandsbudget – 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:
TimeEntry auf den heutigen Tag.cd /pfad/zu/redmine
unzip at_zeiterfassung-1.7.0.zip -d plugins/
bundle exec rake redmine:plugins:migrate NAME=at_zeiterfassung RAILS_ENV=production
# Redmine neu startenAls Administrator einloggen und Administration → Plugins öffnen. Das Plugin Zeiterfassung sollte mit Version 1.7.0 erscheinen. In der oberen Navigation sollte für Benutzer mit dem Recht Eigene Zeiterfassung ansehen der Eintrag Zeiterfassung auftauchen.
Ein Redmine-Update ist für das Plugin nur dann unkritisch, wenn die Reihenfolge stimmt. Redmine lädt jedes Plugin beim Start; passt ein Plugin nicht zur neuen Version, startet die ganze Instanz nicht, bis der Plugin-Ordner entfernt ist. Die Daten in den Plugin-Tabellen sind davon nie betroffen.
Regel: Jede Plugin-Version unterstützt die aktuelle und die vorherige Redmine-Linie (derzeit 5.1 und 6). Welche Plugin-Version mit welcher Redmine-Version getestet ist, steht in der Freigabe-Übersicht auf redmine-plugins.atori.de.
Reihenfolge beim Update:
redmine:plugins:migrate, Neustart) und auf der alten Redmine-Version kurz prüfen. Diese Brückenversion läuft auf beiden Redmine-Versionen.bundle exec rake redmine:plugins:migrate RAILS_ENV=production und Neustart.Fallweg, wenn keine Brückenversion existiert (etwa weil die neue Redmine-Version ein neueres Ruby verlangt):
cd /pfad/zu/redmine
mv plugins/at_zeiterfassung ../at_zeiterfassung.alt # Ordner beiseitelegen, NICHT migrieren
# Redmine aktualisieren
# neue Plugin-Version nach plugins/at_zeiterfassung entpacken
bundle exec rake redmine:plugins:migrate NAME=at_zeiterfassung RAILS_ENV=production
# Redmine neu startenDie Plugin-Tabellen bleiben dabei unverändert in der Datenbank; die neue Plugin-Version hebt das Schema mit ihren eigenen Migrationen an.
> Nie VERSION=0 als Teil eines Updates. Die Rückwärtsmigration auf > Version 0 löscht die Plugin-Tabellen und damit alle Daten des Plugins. > Sie gehört ausschließlich zur endgültigen Deinstallation (siehe unten).
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 startenDer 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.
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 | — |
Fünf Rechte stehen unter Administration → Rollen und Rechte → Zeiterfassung zur Verfügung:
| Recht | Geltungsbereich | Wirkung | Typische Rolle |
|---|---|---|---|
| Eigene Zeiterfassung ansehen | global | Nutzung von Wochengrid, Timer, Favoriten; Perioden einreichen | Jeder Benutzer |
| Zeiterfassung genehmigen | projektbezogen | Submissions der eigenen Projekte sehen, genehmigen / ablehnen / wieder öffnen | Projektleitung |
| Alle Zeiterfassungen genehmigen | global | Submissions aller Projekte sehen und genehmigen | Zentrales PMO / Stellvertretung |
| Projektbudget verwalten | projektbezogen | Reiter Budget sehen und das Aufwandsbudget des Projekts setzen | Projektleitung |
| Portal-Export verwalten | projektbezogen | Reiter Portal-Export sehen und dem Projekt ein Exportformat zuordnen | Projektleitung |
> Upgrade-Hinweis (1.4.x → 1.5.0): Bestehende Wochen-Submissions werden > bei der Migration automatisch pro Projekt aufgesplittet. Rollen, die bisher > Zeiterfassung genehmigen global hatten, sollten nun zusätzlich > Alle Zeiterfassungen genehmigen erhalten, um denselben Umfang zu behalten.
Zeiterfassung in der oberen Navigation öffnet die aktuelle Woche. Linke Seite: Wochengrid. Rechte Seite: Timer.
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.
Buchungen verschieben und kopieren (Blockansicht). Ein Block lässt sich mit der Maus auf einen anderen Tag oder eine andere Zeile ziehen; das verschiebt die Buchung. Ist beim Anfassen des Blocks die Strg-Taste gedrückt (Mac: Cmd oder Alt), wird die Buchung kopiert — die Zielzelle zeigt das während des Ziehens an. Die Taste beim Start gedrückt zu halten ist entscheidend: manche Browser melden sie während des Ziehens nicht mehr.
Buchung löschen. Zelle anklicken, im Dialog den Papierkorb neben der Buchung wählen. In eingereichten oder genehmigten Perioden sind die Zellen gesperrt; dort ist weder Löschen noch Verschieben möglich.
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).
Mehrere Timer parallel: Es können beliebig viele Timer gleichzeitig laufen, je einer pro Ticket. Jeder Timer wird im Panel als eigene Zeile mit laufender Dauer angezeigt.
Pausieren / Fortsetzen: Ein Timer lässt sich pausieren und später fortsetzen; die bereits gelaufene Zeit wird aufaddiert, nicht verworfen.
Stoppen & buchen schreibt einen TimeEntry auf den heutigen Tag mit der aufsummierten Zeit und entfernt den Timer aus dem Panel. Ein Timer lässt sich auch ohne Eintrag verwerfen.
Ticket automatisch übernehmen: Ist das Ticket durch die Eingabe eindeutig bestimmt (exakte ID oder genau ein Treffer), wird es beim Verlassen des Eingabefeldes automatisch ausgewählt.
Aufrunden auf Mindestgranularität: Ist das Plugin at_rechnungstellung installiert und für den zugehörigen Kunden eine Mindestgranularität (in Minuten) hinterlegt, wird die gebuchte Zeit beim Stoppen auf diese Einheit aufgerundet.
Jede Ticketzeile im Grid hat links einen kleinen grauen Stern. Ein Klick darauf macht das Ticket zum Favoriten; der Stern wird orange. Die Zeile des Tickets erscheint ab dann in jeder Woche von selbst, auch wenn noch nichts darauf gebucht ist. Das Ticket muss also nicht jede Woche neu gesucht werden. Stern erneut klicken zum Entfernen; die Zeile verschwindet dann in Wochen ohne Buchung.
Der Stern ist nur in vorhandenen Zeilen sichtbar. In einer Woche ohne Buchungen und ohne Favoriten ist das Grid leer; das Ticket zuerst über das Suchfeld + Eintrag hinzufügen am Ende des Grids einfügen, dann markieren. Favoriten sind benutzerspezifisch; die Liste eines Benutzers beeinflusst keine andere. Eine eigene Favoritenliste oder eine Vorsortierung im Ticket-Picker gibt es nicht.
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.
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.
Einreichungen erfolgen pro Projekt für eine Woche oder einen Monat. Zwei Wege stehen zur Verfügung:
Nach dem Einreichen sind die Zellen des betreffenden Projekts gesperrt; andere Projekte bleiben weiterhin editierbar.
Benutzer mit dem Recht Zeiterfassung genehmigen sehen unter Zeiterfassung → Genehmigungen Submissions ihrer Projekte; Benutzer mit Alle Zeiterfassungen genehmigen sehen alle Submissions. Pro Submission stehen zur Verfügung:
updated_at und reviewer_id der Submission.Im Projekt unter Konfiguration → Budget lässt sich ein Gesamt- Aufwandsbudget in ganzen Stunden hinterlegen. Der Reiter erscheint, wenn das Modul Zeiterfassung (Zeiterfassung/Time tracking) im Projekt aktiviert ist und die aufrufende Person das Recht Projektbudget verwalten besitzt.
Der Reiter stellt gegenüber:
Ein Balken zeigt den verbrauchten (grün) und den noch geplanten (orange) Anteil am Budget; bei Überschreitung markiert eine Linie die Budgetgrenze.
Restaufwand am Ticket. Jedes Ticket weist einen verbleibenden Aufwand aus. Standardmäßig wird er berechnet als geschätzter Aufwand − gebuchte Stunden (nie kleiner als 0). Im Ticket-Formular kann unter Geschätzter Aufwand ein abweichender Restaufwand (h) eingetragen werden. Dieser manuelle Wert hat Vorrang, verändert aber weder den geschätzten Aufwand noch die gebuchten Stunden. Ein leeres Feld stellt den berechneten Wert wieder her.
Wer über einen Personaldienstleister beim Kunden arbeitet, muss seine Stunden zusätzlich in dessen Portal erfassen. Das Plugin erzeugt dafür aus einer eingereichten oder genehmigten Periode eine Datei, die das Portal importiert — ohne Tippen und ohne Spaltenzuordnung.
Zuordnung: Projekteinstellungen → Reiter Portal-Export → Format wählen (derzeit MyTime by Hays), optional eine Referenz wie die Vertragsnummer, die im Dateinamen landet. Nur Projekte mit Zuordnung zeigen den Export; alle anderen bleiben unverändert. Die verfügbaren Formate stehen in den Plugin-Einstellungen.
Export: Einreichung öffnen (über das Badge im Grid oder die Liste Einreichungen) → Export für MyTime by Hays (XLSX) oben rechts. In MyTime dann Import → Projekt wählen → Datei hochladen → Leistungsart für alle oder je Zeile setzen → Import abschließen. Wann eine Periode zuletzt exportiert wurde, steht in der Kopfzeile der Einreichung.
Die MyTime-Datei enthält je Buchung eine Zeile mit Datum, Stunden (hh:mm) und Beschreibung — dem Buchungskommentar, ersatzweise dem Ticket, sonst der Tätigkeit. Von, Bis und Pause bleiben leer: MyTime verlangt nur Datum und Dauer. Spaltennamen und Formate sind gegen den Import des Portals geprüft; ein echtes Excel-Datum würde MyTime mit vertauschtem Tag und Monat lesen, deshalb steht es als Text in der Datei.
Weitere Portale werden als Format ergänzt, sobald ihr Import gegen die echte Oberfläche geprüft ist — ein Format, das nicht verifiziert wurde, hilft niemandem.
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 – Projekt scheint gesperrt. Den Zustand der Submission für dieses Projekt unter Genehmigungen prüfen. Eine eingereichte oder genehmigte Submission sperrt das betreffende Projekt – und zwar in allen Eingabewegen, auch im Standard-Dialog „Aufwand buchen", im Projekt-Zeitprotokoll und über die API, nicht nur im Grid. Ein Genehmiger muss die Submission ablehnen oder wiedereröffnen, damit das Editieren wieder möglich ist; Administratoren können gesperrte Perioden jederzeit bearbeiten. Andere Projekte derselben Periode sind nicht betroffen.
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.
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:
log/production.log, sofern verfügbar