Version 1.7.0 · Redmine 5.1 and 6 · GPLv2
This manual covers installation, configuration and daily use of the atori time-tracking plugin.
The plugin adds a weekly grid timesheet, multiple parallel timers, a monthly view, a two-step approval workflow and a per-project effort budget on top of Redmine's standard TimeEntry model. No parallel time store, no shadow data: entries written here are regular Redmine time entries that show up in the usual reports, issue views and API.
Key concepts:
TimeEntry on the current day.cd /path/to/redmine
unzip at_zeiterfassung-1.7.0.zip -d plugins/
bundle exec rake redmine:plugins:migrate NAME=at_zeiterfassung RAILS_ENV=production
# restart RedmineAfter restart, log in as administrator and open Administration → Plugins. The Zeiterfassung plugin should appear with version 1.7.0. A Zeiterfassung entry should appear in the top navigation for users that have the View own timesheet permission.
A Redmine update is harmless for the plugin only if the order is right. Redmine loads every plugin at start-up; if a plugin does not match the new version, the whole instance fails to start until the plugin folder is removed. The data in the plugin tables is never affected.
Rule: every plugin version supports the current and the previous Redmine line (currently 5.1 and 6). Which plugin version is tested with which Redmine version is listed in the compatibility overview on redmine-plugins.atori.de.
Order of operations:
redmine:plugins:migrate, restart) and verify briefly on the old Redmine version. This bridging version runs on both Redmine versions.bundle exec rake redmine:plugins:migrate RAILS_ENV=production again and restart.Fallback when no bridging version exists (for example because the new Redmine requires a newer Ruby):
cd /path/to/redmine
mv plugins/at_zeiterfassung ../at_zeiterfassung.old # set the folder aside, do NOT migrate
# update Redmine
# unpack the new plugin version into plugins/at_zeiterfassung
bundle exec rake redmine:plugins:migrate NAME=at_zeiterfassung RAILS_ENV=production
# restart RedmineThe plugin tables stay untouched in the database; the new plugin version brings the schema up to date with its own migrations.
> Never run VERSION=0 as part of an update. Rolling the migrations back > to version 0 drops the plugin tables and with them all plugin data. It > belongs to a final uninstall only (see below).
cd /path/to/redmine
bundle exec rake redmine:plugins:migrate NAME=at_zeiterfassung VERSION=0 RAILS_ENV=production
rm -rf plugins/at_zeiterfassung
# restart RedmineThe rake task removes the plugin-owned tables (timers, favourite issues, timesheet submissions). Redmine's TimeEntry data written through the plugin remains intact and continues to work with the core time-tracking UI.
Open Administration → Plugins → Zeiterfassung → Configure:
| Setting | Purpose | Default |
|---|---|---|
| Daily target hours | Reference value for daily/weekly total colouring | 8.0 |
| Workdays | Days of the week that count as work days | Mon–Fri |
| Allow future entries | Whether time can be logged for dates after today | no |
| Lock submitted weeks | Whether submitted/approved weeks are read-only | yes |
| Default activity | Pre-selected activity in new entries | — |
Three permissions are exposed under Administration → Roles and permissions → Zeiterfassung:
| Permission | Scope | Effect | Typical role |
|---|---|---|---|
| View own timesheet | global | Use the weekly grid, timer, favourites; submit periods | Any user |
| Approve timesheets | project-level | See and approve submissions for own projects only | Project manager |
| Approve all timesheets | global | See and approve submissions for any project | Central PMO / deputy |
| Manage project budget | project-level | See the Budget tab and set the project's effort budget | Project manager |
| Manage portal export | project | See the Portal export tab and assign an export format to the project | Project lead |
> Upgrade note (1.4.x → 1.5.0): existing weekly submissions are split per > project automatically during redmine:plugins:migrate. Roles that previously > held Approve timesheets globally should also be granted Approve all > timesheets to retain the same approval scope.
Zeiterfassung in the top navigation opens the current week. The left side is the weekly grid; the right side hosts the timer.
Click a cell for the desired day / issue combination, type the hours, confirm with Enter. The entry is written as a TimeEntry and the daily and weekly totals update without a page reload.
To add a new issue row, use the Add entry search at the bottom of the grid. Enter an issue ID or type to search by subject. Activity and comment fields are inline on the row.
Moving and copying bookings (block view). Drag a block to another day or row to move the booking. Hold Ctrl (Mac: Cmd or Alt) while picking the block up to copy it instead -- the target cell shows the difference while you drag. Holding the key at the start matters: some browsers stop reporting it once the drag is under way.
Deleting a booking. Click the cell and use the bin next to the booking in the dialog. Cells of a submitted or approved period are locked; nothing can be deleted or moved there.
In the Timer panel on the right, enter an issue ID or search term, optional comment, and click Start timer. The timer runs in the background even across logouts (state is persisted server-side).
Multiple timers in parallel: any number of timers can run at the same time, one per issue. Each appears as its own row with a live elapsed duration.
Pause / resume: a timer can be paused and later resumed; the time already elapsed is accumulated, not discarded.
Stop & log writes a TimeEntry on the current day for the accumulated time and removes the timer from the panel. You can also discard a timer without writing any entry.
Auto-select the issue: when your input uniquely identifies the issue (an exact id or a single match), it is selected automatically as you leave the input field.
Rounding to a minimum granularity: if at_rechnungstellung is installed and the related customer has a minimum granularity (in minutes) configured, the logged time is rounded up to that unit when you stop the timer.
Every issue row in the grid has a small grey star on the left. Click it to make the issue a favourite; the star turns orange. From then on the issue's row appears in every week by itself, even before anything is logged on it, so you don't have to look the issue up each week. Unstar it to remove the favourite; the row then disappears in weeks without entries.
The star is only visible in existing rows. In a week with no entries and no favourites the grid is empty; add the issue via the + Add entry search field at the bottom of the grid first, then star it. Favourites are per user; one user's list doesn't affect another's. There is no separate favourites list and no favourites-first ordering in the issue picker.
Click Copy previous week to duplicate the structure of the preceding week's entries (issues and activities) into the current week with zero hours. Useful for teams that recurrently work on the same set of issues and only need to fill in the quantities.
Switch between Week and Month on the view toggle. The monthly view shows a compact per-day summary across all weeks of the selected month. Useful for reporting and sanity checks; editing still happens in the weekly grid.
The selected period (week/month) and view mode (compact/blocks) are remembered per user. The next visit to the timesheet without explicit query parameters opens in the view you used last.
Submissions are created per project and cover a week or a full month. Two entry points are available:
After submitting, the cells of the affected project are locked; other projects in the same period remain editable.
Users with Approve timesheets open Zeiterfassung → Approvals to see submissions for their projects. Users with Approve all timesheets see every submission. For each submission they can:
updated_at and reviewer_id fields of the submission.Under a project's Settings → Budget, you can store a total effort budget in whole hours. The tab appears when the Time tracking module is enabled for the project and the caller holds Manage project budget.
The tab compares:
A bar shows the consumed (green) and still-planned (orange) share of the budget; when over budget, a line marks the budget boundary.
Remaining effort on the issue. Every issue carries a remaining effort. By default it is computed as estimated − spent (never below 0). In the issue form, below Estimated time, a different Remaining effort (h) can be entered. This manual value takes precedence but changes neither the estimated hours nor the logged time. Clearing the field restores the computed value.
Contractors placed through a staffing agency have to record their hours a second time in the agency's portal. The plugin turns a submitted or approved period into a file that portal imports -- no typing, no column mapping.
Assignment: project settings -> Portal export tab -> choose the format (currently MyTime by Hays), optionally a reference such as the contract number, which goes into the file name. Only projects with an assignment show the export; every other project is untouched. The available formats are listed in the plugin settings.
Export: open the submission (via the badge in the grid or the Submissions list) and click Export for MyTime by Hays (XLSX) at the top right. In MyTime: Import -> choose the project -> upload the file -> set the service type for all rows or per row -> finish the import. The submission's header shows when it was last exported.
The MyTime file has one row per booking with date, hours (hh:mm) and a description -- the booking's comment, else the ticket, else the activity. Von, Bis and Pause stay empty: MyTime requires only date and duration. Column names and formats were verified against the portal's import; a real Excel date is read by MyTime with day and month swapped, which is why the date is text.
Further portals are added as formats once their import has been verified against the real interface -- an unverified format helps nobody.
Zeiterfassung not in the top menu. The user needs the View own timesheet permission in at least one role. Assign the permission at Administration → Roles and permissions.
Can't add entries – project appears locked. Check the state of that project's submission under Approvals. A submitted or approved submission locks that project by design — in every entry point, including the standard "Log time" dialog, the project time log and the API, not only the grid. A reviewer must reject or reopen it to enable editing; administrators can edit locked periods at any time. Other projects in the same period are not affected.
Timer doesn't stop / gets stuck. Reload the page. The timer state lives on the server; a browser-side hang is cosmetic. In rare cases (e.g. a crashed browser mid-start), cancel the timer from the timer panel and start a fresh one.
Favourites not sticking. Favourites are scoped to the user. Make sure you're logged in as the intended user, not as a shared demo account.
Entries appear in Redmine reports but not in the grid. The grid displays entries within the user's visible projects for the current week. Cross-check the week (top navigation) and the project membership of the user.
Support is included for twelve months from the date of purchase.
E-mail: support@atori.de Initial response: within 48 hours on business days.
When reporting issues, please include:
log/production.log, if available