DEV Community

Cover image for Timesheet Guardian: an n8n workflow that checks time tracking against German working-time law
Daniele Michelin
Daniele Michelin

Posted on Edited on Originally published at daniele-michelin.com

Timesheet Guardian: an n8n workflow that checks time tracking against German working-time law

Try the Timesheet Guardian → The page checks an entry in your browser and draws a live chart. The real forms are at mikweb.eu/form/zeitwaechter (hours) and /zeitwaechter-abwesenheit (absences). The demo data is made up (Musterbüro GmbH); in real use it runs on real Nextcloud accounts, see below.

Why bother

Since the Federal Labour Court ruling of 13 September 2022 (1 ABR 22/21), German employers have to record working time. A spreadsheet often does the job. What it does not do is tell you that someone worked 11 hours yesterday without a proper break and starts again at 06:00 today. That usually surfaces when someone reads the list at month end. I wanted the violation to trigger a card and a message the same evening, with nothing more exotic than n8n, Nextcloud and a CSV.

Legal status: the recording duty has applied since 2022. A reform of the Working Hours Act (a draft from the federal labour ministry) had not been passed as far as I knew in June 2026. Check where it stands today. This is a technical example and not legal advice.

What the workflow does

  1. Two n8n forms: hours (person, date, start, end, break, project, activity) and absence (person, from, to, kind: vacation, sick leave or flextime off).
  2. Validation of the input (format, times, date), then saving to zeiten.csv in Nextcloud over WebDAV.
  3. ArbZG check over all rows, then a comparison with the state before the entry: only new violations trigger anything.
  4. On a new violation: a card in Nextcloud Deck and a message in Talk.
  5. Absences become CalDAV events. A second check finds hours logged on a day of absence.
  6. Friday 15:00: a weekly report as Markdown and as an SVG dashboard in Nextcloud, plus Talk.
  7. Monday: the demo data is reset.
  8. Per account: calendar, Deck board, Talk chat and folder are created automatically (see "Real Nextcloud accounts" below).

The rules

  • Section 3: at most 10 hours a day, 8 hours on average.
  • Section 4: a 30-minute break after more than 6 hours, 45 minutes after more than 9.
  • Section 5: 11 hours of uninterrupted rest between two working days.
  • Section 9: Sunday work.
  • Hint: more than 48 hours in a week. A hint, not a violation: the law works with averages.

All of it is deterministic code (core.js, over 100 checks pass in node test_core.js). The AI (IONOS gpt-oss-120b) writes only three sentences of the weekly report and sees no names, only numbers. Whether someone broke the law is never decided by a language model.

Concurrent writes: ETag and If-Match

Two people submit at the same time, both read the CSV, both write it back: one entry is gone. So, optimistic locking over WebDAV: GET returns the file with its ETag, and the PUT sends If-Match: <ETag>. If the file changed in between, Nextcloud answers 412 Precondition Failed. The workflow then reads again and retries, up to three times. After the third failure it says so, instead of overwriting something silently.

What I learned on n8n 2.46.6

  1. Do not set "Respond When" to "Using Respond to Webhook". With Form Trigger v2.5 and the n8n Form node you get "Respond to Webhook not supported in workflows initiated by Form Trigger" or "No Respond to Webhook node found". Leave the default: the Form node gives the response.
  2. The Form node's Completion operation with "Show Text" accepts full HTML. The response can be an entire page, including an inline SVG chart. Mechanically: the form POST returns JSON with formWaitingUrl, the browser goes to /form-waiting/<id>, and the page appears there.
  3. HTTP Request with full response and text: the content is in data, not body. My res.body was undefined and the CSV was rewritten with a single row. Since then there is a data-loss guard: if parsing yields zero rows although the file is not empty, the run stops instead of writing.
  4. Which of the five triggers fired? Check $('Node').isExecuted; that lets one workflow serve all of them.
  5. The Code node has no URL class. Use regular expressions.
  6. CSV injection. Cells starting with =, +, - or @ get a leading '. Otherwise Excel runs a formula hidden in a project name.
  7. Nextcloud WebDAV: If-Match with the ETag from the GET works, and a stale ETag gives 412. That is exactly what you need.

Clock in with a QR code: no form anymore

Forms suit office people. Anyone on the shop floor, in the warehouse or on the road just wants to scan. So there is a second path, again entirely in n8n and Nextcloud:

  1. Register the phone once (/en/zeit/register/): pick a person, the phone gets a random device token. Only its SHA-256 hash is stored, in geraete.json in Nextcloud. With real accounts, sign-in goes through Nextcloud Login Flow v2 (see below); the demo page uses the fictional people.
  2. Daily QR at the entrance (/en/zeit-qr/): four codes (start, break, resume, end). Each is an HMAC-SHA-256 of date and kind, with the key only on the server. Tomorrow every code is different, so a photo from yesterday is useless.
  3. Scan with the camera: the page punches by itself. n8n sets the time (the server's Berlin time), never the phone. Only on end a field for the activity appears.
  4. State machine per person and day: start, (break, resume) any number of times, end. Start twice gives wrong_state. Every punch lands in stempel.csv.
  5. On end it becomes a booking and goes through the same nodes as the form: overlap, ArbZG check, Deck, Talk, absence calendar.

Two notes: SHA-256 and HMAC are plain JavaScript inside the Code node (no crypto, no require), checked against the RFC 4231 test vectors. And honestly: a QR code can be photographed and forwarded. The device token and the daily code make that harder, they do not prevent it. A screen with a rotating code or a location check would be the next step. Time data tied to a private phone is personal data: in real use you need information and a legal basis (works council, data protection).

Everyone sees their own time, the boss sees everything: real Nextcloud accounts

The Guardian started as a demo with four made-up names in one shared CSV. It now runs on real Nextcloud accounts, and each person gets their own views.

Three groups

  • zeit-team: the employees.
  • zeit-chef: the boss.
  • zeit-demo: the fictional demo accounts Anna, Ben, Chiara, Dario and "Chef demo", with a 20 MB quota and no permission to share. Visitors to this page do not log in: they use the "pick a person" demo.

My own account is not an admin. It is an employee and the boss, so it sits in both groups.

Registering the phone: Login Flow v2, no stored password

  1. The PWA opens the Nextcloud login (Login Flow v2).
  2. n8n receives an app password, checks that the person is in zeit-team, and revokes the app password immediately.
  3. Only a device token is issued, and only its SHA-256 hash is stored.

So no Nextcloud password stays behind, neither in the browser nor in n8n.

The "zeitwaechter" bot sets everything up

A non-admin bot account creates and maintains, for every user:

  • a "Arbeitszeit" calendar, read-only for the user and for the boss group,
  • a Deck board "Meine Zeit" (weeks and violations),
  • a private Talk chat for confirmations and warnings,
  • a Files folder Zeit/<user>/ with the CSV, Woche.svg (chart of the week) and Wochen.md (table).

For the boss there is also a Deck board "Zeit-Übersicht" (one column per person plus "Da chiarire"), a Talk room "Zeit-Team (Chef)" and a folder Zeit/Team/ with Dashboard.svg, Uebersicht.md and the Friday reports. The bot is subadmin of zeit-team and zeit-chef only, so it can read the members and nothing more.

Charts in the PWA

At /en/zeit/charts/ there is "My week" for everyone and "Team" for the boss, each with a chart, a table, CSV export and print/PDF.

Repeatable, and checked

Onboarding can be run again and again. If a share fails, the bot retries once, and the seed result reports problems as a warning. Verified with occ and OCS: Ben sees only his own calendar and board, the boss sees everything.

For other Nextcloud instances

The guide and scripts (setup.sh, uninstall.sh) are at /en/timesheet-guardian/nextcloud/, and the setup script is also available as the file zeitwaechter-setup.sh.

Honest limits

  • Hours tied to a person are personal data: informing staff, a legal basis and the works council are your job.
  • The boss sees everything, by construction.
  • A demo user with a login could list other accounts, which is why there is no public demo login.
  • This is not legal advice.

What it looks like in Nextcloud

Real screenshots from the demo setup on my Nextcloud (fictional people of Musterbüro GmbH, taken with the boss account).

What it looks like in Nextcloud

Real screenshots from the demo setup (fictional people).

Deck: the «Zeit-Übersicht» board for the boss, one column per person plus a «Da chiarire» column for rule violations.
Deck: the «Zeit-Übersicht» board for the boss, one column per person plus a «Da chiarire» column for rule violations.

Calendar: one shared «Arbeitszeit» calendar per person, every day is an event with net hours.
Calendar: one shared «Arbeitszeit» calendar per person, every day is an event with net hours.

Talk: the bot confirms every punch and warns about violations.
Talk: the bot confirms every punch and warns about violations.

Dashboard.svg in Nextcloud
Files: the boss's weekly dashboard as an SVG in Zeit/Team/Dashboard.svg, refreshed on every punch (plus Uebersicht.md).

Try it and download it

Download the workflow JSON → Import it, add your own Nextcloud and IONOS credentials, and adjust the Nextcloud path, Deck board and Talk room. No secrets are in the JSON. The AI sentences are optional: without the credential the report keeps the numbers.

Limits

This is a demo setup, not a production timekeeping system. The data is made up. No works council, no collective agreements, no exceptions under section 7 or sector rules (care, hospitality, transport), and different rules apply to minors, pregnant employees and drivers. The thresholds follow the text of the law but do not replace a review by someone who knows your company. What the reform changes is not covered here: please read up on the current state.

Related: the Rubber Stamp Test shows why "a human looks at it" is not enough on its own. Here the code does the checking, and the human only sees the cases that matter.


Originally published at daniele-michelin.com. More guides, free checks (SPF, TLS, headers) and an error-message lexicon: daniele-michelin.com/en/.

Top comments (1)

Collapse
 
vietautomation profile image
Viet Automation •

Keeping the legal decision in deterministic code, with the model only allowed to write three sentences of numbers, is the right split. The ETag/If-Match loop that gives up loudly after three 412s is also more careful than most CSV-on-WebDAV setups I've seen.

A few things I'd look at:

  • The data-loss guard catches "zero rows from a non-empty file", but not a partial parse. One activity field with a quoted newline, or a stray delimiter, can turn 400 rows into 380 and still look valid. Since every form submission adds exactly one booking, you could only allow the PUT when the new row count is exactly the old count plus one (or the same count for an edit). Anything else stops the run.
  • DST nights. If durations come from Berlin wall-clock strings, a shift across the last Sunday of October is an hour longer than start/end suggest, and one in March is an hour shorter. That's enough to flip a §3 (10 h) or §5 (11 h rest) result. Storing the UTC offset with each punch, or computing on UTC timestamps, makes those checks hold up on those nights too.
  • "Only new violations trigger" is worth keying explicitly, e.g. person + rule + date (or the pair of dates for §5), instead of comparing counts before and after. Otherwise correcting yesterday's end time can clear one rest-period violation and create another, the count stays the same, and nobody gets a card.
  • Small one on CSV injection: OWASP's list also includes cells starting with a tab or carriage return, besides = + - @.