Staff Management - wiso-forschungslabor/hroot-documentation GitHub Wiki

[!NOTE] Who is "Staff"? In hroot, the term Staff (Personal) refers collectively to all internal team members involved in lab operations (Administrators, Banking-Administrators, and Experimenters / Student Assistants / HiWis) who execute tasks, run sessions, or submit working time availabilities.

1. Task Management & Workflow Buckets

hroot provides a powerful task management workflow to automate checklists and track responsibilities before, during, and after experiments.

  • Module Activation: Enabled under Site Settings -> Plugins / Features (/admin/options/features) via the switch Staff Tasks (Aufgabenverwaltung).
  • Configuration Location: Task templates, buckets (phases), and project step definitions are managed under Site Settings -> Project steps (/admin/options/project_steps).

1.1. Core Concept: Buckets vs. Procedure Ablaufplan

It is essential to distinguish between Project Steps & Buckets and the Session Procedure (Ablaufplan):

  • Task Buckets & Staff Tasks (Project Steps): These represent the administrative and organizational checklists across the lifecycle of an experiment (e.g. Preparation: submit ethics application, verify survey software; Execution: prepare lab computers; Post-processing: export data, reconcile payout receipts). Tasks are created dynamically when a phase is reached and assigned to staff members.
  • Session Procedure (Ablaufplan): This is the in-session script and timeline protocol for experimenters executing a specific session (e.g. 00:00–00:10 Admission & Seating, 00:10–00:25 Read instructions, 00:25–00:55 Treatment on PC, 00:55–01:05 Participant payouts). The Procedure contains instructions, links to experimental files, can be downloaded as PDF or embedded in calendar ICS invites, and is independent of administrative To-Do tasks. See Managing Experiments#2-procedures--versions for details.

1.2. Global Configuration: Buckets & Task Templates

Under Site Settings -> Project steps (/admin/options/project_steps), administrators configure the building blocks:

  • Task Buckets (Phasen / Aufgabenpakete): Ordered containers representing project phases (e.g. 1. Vorbereitung, 2. Durchführung, 3. Nachbereitung).
  • Task Templates (Aufgaben-Vorlagen): Blueprints for reusable tasks. Each template defines:
    • Title and description / instructions.
    • Default priority (Low, Medium, High).
    • Recurrence (e.g. Once, Daily, Weekly, Monthly).
    • Estimated workload (hours) and default due date offset (days after phase start).
    • Optional default assignee.
  • Project Templates (Projekttypen / Vorlagen für Experimente): Group specific buckets and task templates together (e.g. "Standard Lab Experiment", "Online Survey", "Eye-tracking Study"). When an experiment is associated with a project template, only the relevant buckets for that study type are displayed in its tasks view.

1.3. Phase Activation in Experiments (Bucket Activation Workflow)

In the experiment's Tasks tab, phases follow an explicit activation lifecycle:

  1. Initial Inactive State: When a new experiment is set up, all configured buckets start in an inactive state (displayed with reduced opacity and blurred task lists in the Kanban board). No actual tasks are created yet, preventing task clutter for future phases.
  2. Activating a Phase (Aktivieren): As the experiment reaches a milestone, the researcher clicks Activate (Aktivieren) on the respective bucket.
  3. Automated Task Instantiation: Upon activation, hroot automatically instantiates all TaskTemplate records associated with that bucket into active StaffTask records for this experiment.
  4. Phase Deadline: Each active bucket can be given a phase deadline date (Fälligkeitsdatum) directly in the header, keeping milestones on track.
  5. Deactivation: If a bucket is deactivated, the uncompleted template tasks for that bucket are cleanly removed.

1.4. Session-Repeat Phases (Session-Wiederholungen)

Certain tasks must be carried out for every individual session rather than just once for the whole experiment (e.g., ventilating the lab room 15 minutes before the session, printing participant sign-in sheets, verifying seating layout).

  • Session Phase Flag (session_phase = true): A bucket can be marked as a Session-Repeat Phase. In the UI, it displays a distinct orange badge (Session-Wiederholung).
  • Session-Level Generation: Tasks belonging to a session-repeat bucket are automatically generated per session, linking each task directly to its corresponding session datetime and location.

1.5. Staff Assignment & Kanban Dashboard

  • Delegating Tasks: Tasks can be assigned to individual team members (assigned_to) or co-assigned to multiple users.
  • Personal Dashboard: When staff members log in, their assigned tasks appear directly on their personal dashboard in an interactive Kanban Board with columns:
    • Open (Offen)
    • In Progress (In Bearbeitung)
    • Completed (Erledigt)
    • Cancelled (Abgebrochen)
  • Real-Time Drag & Drop: Team members can drag cards between status columns, mark items complete, or view task descriptions with one click.
  • Automated Email Notifications: When a task is assigned, updated, or removed, the assigned staff member receives an email notification.

1.6. Permissions & Delegation

  • Creating & Delegating: Any standard Administrator or Experimenter with appropriate rights can create tasks and delegate them to active team members.
  • Editing Scope: Standard Administrators can view all tasks across the system, and can edit, update status, or delete tasks that they created (created_by) or that are assigned to them (assigned_to).
  • Full Task Governance: Banking-Administrators have full administrative authority to edit, reassign, or delete any task in the system, even if created by and assigned to other team members.

2. Staff Availabilities & Shift Plans (Einsatzpläne)

To coordinate session staffing and lab supervision (experimenters, lab assistants, HiWis), hroot combines individual availability tracking with an automated shift planning and dispatch system.

  • Module Activation: Enabled under Site Settings -> Plugins / Features (/admin/options/features) via Staff Availabilities (Mitarbeiter-Verfügbarkeiten).

2.1. Recurring & One-Time Availabilities

Staff members maintain their availability directly in their profile settings:

  • Recurring Slots: Weekly repeating working time slots (e.g. Every Wednesday 10:00 – 14:00), with support for bi-weekly intervals and validity date ranges (e.g. valid for the current semester).
  • One-Time Slots & Exceptions: Specific date-and-time overrides or blocked days (e.g. exam periods, sickness, or vacation).
  • Weekly Confirmation Flow: Staff can confirm their availability week-by-week. If an upcoming week is unconfirmed, warning flags alert administrators.
  • Permissions: Standard staff can view and edit their own working times. Banking-Administrators have full access to view, edit, and configure availabilities for all staff members.

2.2. Calendar Integration & Staffing Matching

  • Availabilities Overlay: In the calendar view (/calendar), administrators can toggle "Show availabilities" (Verfügbarkeiten anzeigen).
  • Visual Staff Matching: Beside each scheduled session, available staff members are highlighted based on their configured working times. This allows administrators to assign qualified experimenters and student assistants without scheduling conflicts.

2.3. Generating & Dispatching Shift Plans (/calendar/shift_plan)

Once sessions and tasks have been assigned, administrators can generate and distribute an official Shift Plan (Einsatzplan):

  1. Accessing Shift Plan Generation: Navigate to Calendar -> Shift Plan (/calendar/shift_plan).
  2. Selecting Timeframe: Choose a start and end date (e.g., the upcoming week or two weeks).
  3. Preview & Recipient List: hroot compiles all sessions, assigned experimenters, and active staff tasks within the period. The recipient list automatically includes:
    • All experimenters assigned to sessions in the timeframe.
    • All staff members assigned to tasks in the timeframe.
    • Any team members configured to permanently receive shift plans (always_receive_shift_plan).
  4. Sending the Plan: Clicking Send Shift Plan generates individualized emails for each recipient containing a clean, formatted schedule table (#shift_plan_table).

2.4. Automatic Schedule Change Notifications

hroot prevents miscommunication through proactive change tracking:

  • Immediate Alerts for Active Plans: If a session, experimenter assignment, or staff task is rescheduled, reassigned, or deleted within an already dispatched shift plan period, hroot immediately sends a targeted change notification (ShiftPlanMailer.assignment_changed) to the affected staff member.
  • Batched Evening Digest: For schedule adjustments outside active periods, notifications are queued and dispatched in an evening batch (at 18:00) to keep staff informed without flooding their inboxes.

2.5. Shift Plan Settings & Permanent Recipients

Under Site Settings -> Shift Plan (/admin/options/shift_plan), administrators can:

  • Customize Email Templates: Define the default email subject and body for initial shift plans as well as update notices, using placeholders such as #shift_plan_table, #start_date, and #end_date.
  • Manage Permanent Recipients: Add or remove staff members (such as lab coordinators or lead investigators) who should always receive a copy of every distributed shift plan.

3. Two-Factor Authentication (2FA)

To secure administrative accounts, hroot supports Time-based One-Time Passwords (TOTP) for two-factor authentication.

3.1. Enabling 2FA

  • Configuration Location: Navigate to Site Settings -> Plugins / Features (/admin/options/features under System & Plugins).
  • Global Settings: Check the box Admin Zwei-Faktor-Authentifizierung (2FA) (enable_admin_2fa). Once active, TOTP 2FA is required for all accounts with the roles admin and banking_admin.
  • Setup: Upon logging in, staff members are prompted to scan a QR code using an authenticator app (e.g. Google Authenticator, Bitwarden) and verify the setup with a one-time code.
  • Remember Device: Users can check "Trust this device" during login to remember the browser for 90 days.

3.2. Resetting 2FA Tokens

  • Admin Reset: If a staff member loses access to their authenticator device, administrators can reset the 2FA configuration in the user's profile settings. This clears the TOTP secret and allows the user to re-register their device upon their next login.

4. Kimai Absence & Vacation Synchronization

hroot integrates with the time-tracking tool Kimai to automatically synchronize and display staff absences and holidays.

4.1. Absence Sync Workflow

  • Background Sync: hroot queries the Kimai API at regular intervals or on-demand to fetch vacation records, sick leave, and other absences logged by staff members.
  • Automatic Matching: Absences in Kimai are mapped to hroot staff profiles using email addresses.

4.2. Calendar Display

  • Visual Schedule: Synced absences are displayed directly in the hroot calendar view as blocked periods. This prevents administrators from scheduling staff members for sessions during their vacation or sick leave.