{"id":22557966,"url":"https://github.com/pders01/koha-plugin-staff-roster","last_synced_at":"2026-05-02T22:03:36.625Z","repository":{"id":236149182,"uuid":"792016882","full_name":"pders01/koha-plugin-staff-roster","owner":"pders01","description":"This plugin enables you to create rosters to plan your work right from Koha.","archived":false,"fork":false,"pushed_at":"2026-05-02T20:54:45.000Z","size":632,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-02T21:28:48.928Z","etag":null,"topics":["koha-plugin"],"latest_commit_sha":null,"homepage":"","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pders01.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-04-25T20:13:22.000Z","updated_at":"2026-05-02T20:54:49.000Z","dependencies_parsed_at":"2024-04-25T21:28:04.022Z","dependency_job_id":"ce9fa1ce-fde0-4629-a8b5-915b0f4c07be","html_url":"https://github.com/pders01/koha-plugin-staff-roster","commit_stats":null,"previous_names":["pders01/koha-plugin-staff-roster"],"tags_count":0,"template":false,"template_full_name":"pders01/dev-koha-plugin-kitchen-sink","purl":"pkg:github/pders01/koha-plugin-staff-roster","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pders01%2Fkoha-plugin-staff-roster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pders01%2Fkoha-plugin-staff-roster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pders01%2Fkoha-plugin-staff-roster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pders01%2Fkoha-plugin-staff-roster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pders01","download_url":"https://codeload.github.com/pders01/koha-plugin-staff-roster/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pders01%2Fkoha-plugin-staff-roster/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32550918,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T21:31:48.061Z","status":"ssl_error","status_checked_at":"2026-05-02T21:31:46.574Z","response_time":132,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["koha-plugin"],"created_at":"2024-12-07T20:10:17.092Z","updated_at":"2026-05-02T22:03:36.619Z","avatar_url":"https://github.com/pders01.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# koha-plugin-staff-roster\n\nManage staff duty rosters and shifts inside Koha. Drag-and-drop schedule\ngrid, recurring time slots with iCal RRULE, library-group scoping,\ncalendar-aware closures, swap workflow, self-service claim/drop, and\nnightly email reminders. German UI translation included.\n\n\u003e **Status:** pre-alpha (plugin metadata `0.1.0`; GitHub release tag\n\u003e `v0.1.0-alpha.0`, marked as a GitHub pre-release). Built and exercised against\n\u003e Koha **main** throughout development; no other release line has been\n\u003e verified yet. The `minimum_version` metadata field is permissive\n\u003e (24.05+) on the assumption that the touched surfaces are\n\u003e backward-compatible, but installs on older releases should expect to\n\u003e file a bug. The REST surface uses Koha terminology (`patron_id`) so\n\u003e it slots into the rest of the API without surprise.\n\n## Background\n\nThis plugin started as a dual-use exercise: build a real, useful\nKoha extension and, along the way, exercise the plugin system to\nsee what patterns emerge. The roster problem is genuine — desk\nshift management is a recurring need across single-branch and\nmulti-branch libraries — and the result is meant to stand on its\nown as a serious plugin. Adoption will tell us whether it stays\nstandalone or grows beyond that.\n\nTwo side outputs fall out of the work:\n\n- **Templates and patterns for [`pders01/koha-plugin`](https://github.com/pders01/koha-plugin)**,\n  the scaffold CLI that bootstrapped this repo. Recurring shape\n  decisions made here (cpanfile boundaries, package layout, RRule\n  handling, sub-permission registry, additional-fields glue,\n  `_audit` plumbing, the static asset surface, the i18n shim, the\n  Lit + TT bridge, nightly cron entrypoint, `.kpz` packaging, CI\n  shape) are good candidates to fold back into the scaffold so the\n  next plugin that hits the same shape gets a head start.\n- **Possible upstream contributions to Koha itself.** Some helpers\n  here exist as plugin-side workarounds where a small core hook\n  could serve every plugin that needs the same thing — granular\n  sub-permissions under `plugins`, library-group visibility\n  walking, calendar closure merging into per-instance exception\n  rows, the post-25159 `_audit` wrapper. Time permitting, a few\n  of these may become Bugzilla proposals down the line; the plugin\n  is happy to keep carrying them in the meantime.\n\n## Features\n\n- **Schedule grid** — drag staff onto time slots, drop assignments\n  between cells, undo with Cmd-Z, optimistic UI with concurrent-edit\n  highlighting. Keyboard pickup (`Enter` / `Space`, arrow nav, `Esc`\n  cancel) covers HTML5 DnD, keyboard-only, and touch alike.\n- **Recurring slots** — `FREQ=WEEKLY` and `FREQ=MONTHLY` with\n  `BYDAY` (incl. ordinals like `1MO`, `-1FR`), `INTERVAL`, and\n  `UNTIL`.\n- **Library scope** — branch-bound, group-bound, or all-branches\n  rosters. Off / filter / strict modes for cross-branch visibility.\n- **Calendar integration** — Koha holiday calendars merge into\n  exception rows; hard mode blocks assignment on closed dates.\n- **Self-service** — staff can claim open shifts and drop their own,\n  gated by sub-permission, kill-switch setting, and a configurable\n  hour-window lockout.\n- **Swap workflow** — request a one-way handoff or a mutual two-\n  assignment swap; manager approval optional per setting.\n- **Nightly email reminders** — N days before each shift, via a Koha\n  notice template (`STAFFROSTER`/`REMINDER`) admins can edit.\n- **Audit trail** — every mutation flows into Koha's `action_logs`\n  with full pre/post diff support; 409 conflict rejections also emit\n  `CONFLICT_REJECTED` rows so blocked attempts stay reconstructable.\n- **i18n** — English + German shipped (~280 keys); partial\n  translations fall through to English so a missing key never breaks\n  a page. Templated REST errors (`Slot full ({filled}/{max})`,\n  `Self-unclaim closed: must drop at least {hours}h before the shift`)\n  re-render in the active locale.\n\nSee **[docs/wiki/](docs/wiki/Home.md)** for the full user manual,\nconfiguration guide, and architecture notes. The same files double as\nthe GitHub Wiki source. The release log lives in\n**[CHANGELOG.md](CHANGELOG.md)**.\n\n## Install\n\n1. Grab the latest `.kpz` from the project's\n   [GitHub Releases](https://github.com/pders01/koha-plugin-staff-roster/releases)\n   page, or build one yourself:\n\n   ```bash\n   bun install\n   bun run build           # bundles the Lit components into Koha/Plugin/.../staff-roster.js\n   just package            # produces koha-plugin-staff-roster-\u003cversion\u003e.kpz at repo root\n   ```\n\n2. Upload via Koha's plugin admin (Administration → Manage plugins →\n   Upload plugin) and run the installer when prompted.\n\n3. Grant the `staffroster_*` sub-permissions (under the `plugins`\n   flag) to the staff who need them. Superlibrarians always pass.\n\n4. Open **Tools → Staff Roster** to start.\n\n## Configure\n\nDefaults are usable out of the box, but the **Configuration** page\n(under the plugin's tool view) exposes:\n\n- email reminder toggle + days-before\n- library group enforcement mode (off / filter / strict)\n- staff patron-categories filter\n- Koha calendar integration + branch override\n- Koha desks / authorised values for slot locations\n- self-service kill-switch + lockout window\n- swap-approval requirement\n\nSee **[docs/wiki/Configuration.md](docs/wiki/Configuration.md)** for the\nfield-by-field walkthrough.\n\n## Project layout\n\n```\nKoha/Plugin/Xyz/Paulderscheid/StaffRoster.pm     Main module (lifecycle + tool / admin / configure / report dispatchers)\nKoha/Plugin/Xyz/Paulderscheid/StaffRoster/\n  AssignmentController.pm                         REST: assignments + self-service\n  RosterController.pm                             REST: per-roster week view\n  StaffController.pm                              REST: staff lookup + /me endpoints\n  Lib/                                            Helper packages: I18N, DateUtils, Audit, Permissions, Visibility, Rrule, AdditionalFields, Schema\n  Controllers/Tool/                               Per-op handler + view bodies (List, Form, Slots, Exceptions, Swaps, SelfService)\n  *.tt                                            Tool / admin / configure / report templates\n  locales/de.json                                 German UI translations (shared with the JS bundle via src/i18n/de.ts)\ncron/staff_roster_nightly.pl                     Nightly reminder cron entry (FindBin-bootstrapped)\nsrc/                                             Lit components (TypeScript)\nt/                                               Plugin prove tests (live container DB)\ncypress/                                         Cypress integration specs\ndocs/wiki/                                       User manual + GitHub Wiki source\n```\n\n## Testing\n\nInside the kohadev container:\n\n```bash\ndocker cp t dev-koha-1:/var/lib/koha/kohadev/plugins/t\ndocker exec dev-koha-1 sh -c \\\n  \"cd /var/lib/koha/kohadev/plugins \u0026\u0026 \\\n   KOHA_CONF=/etc/koha/sites/kohadev/koha-conf.xml \\\n   prove t/00-load.t t/rrule.t t/self_service.t t/swap_ownership.t \\\n         t/swap_respond.t t/exceptions.t t/additional_fields.t \\\n         t/conflict_check.t t/visibility.t\"\n```\n\n**67 tests across 9 files** cover RRule semantics, self-service flow,\nswap ownership + mutual approve, exception CRUD, additional fields,\nthe `_conflict_check` capacity gate, the recursive group walk, and\nthe load-everything smoke test.\n\nFor the live REST round-trip (calendar merge, exception precedence,\ngrid render, drag-and-drop):\n\n```bash\njust test-cypress\n```\n\nThe script syncs the plugin into the kohadev container, restarts\nPlack, and runs `cypress/integration/staffroster/*_spec.ts` through\nktd's bundled cypress install. **27 tests across 7 specs.**\n\nTo fire the nightly reminder cron once in dev:\n\n```bash\njust cron-nightly\n```\n\n## License\n\nGPL v3.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpders01%2Fkoha-plugin-staff-roster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpders01%2Fkoha-plugin-staff-roster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpders01%2Fkoha-plugin-staff-roster/lists"}