Timesheet

Needs

allow admin to * write notes on specific shift * mark individual timesheet entry as approved * accept ‘clock in’ and ‘clock out’ times as entered, or enter new times * enter time entries for a date for a user unconnected to any hospital or shift

data structure

A ‘timesheet’ table holds info joining a timeperiod against a specific user.

A ‘timesheetentry’ table holds info joining specific shift data (and eventually non-shifts) and admin-managed data (notes, time adjustments, etc).

Initial clock in/out data and user-provided notes are stored in a shift_time table during the clock in/out process. These are referenced and copied over to ‘timesheetentry’ on clock in/out.

setup

When a new timeperiod is created, TimesheetService::updateTimesheetsInPeriod is called which will create or update timesheets for shifts in the period, and create timesheet entries for each assigned or approved shift for an employee.
This can also be triggered via the timesheet screen via ‘update period’ button.

timesheet entry fields

timesheet_id shift_id admin_note reviewed_at scheduled_start scheduled_end clocked_start clocked_start_note clocked_end clocked_end_note final_start final_end

‘final_start’ and ‘final_end’ will be what are used for final timesheet/pay numbers, and will be initially set to whatever clocked_start/end times are set to, whenever these are set (clockin and clockout event listeners are configured to handle that).

An administrator override will be overriding the final_start/end times only.

flow

Admin user will see scheduled time and clock in/out times, if any, along with ‘final’ start/end times. Clicking the pencil icon next to either one allows for editing the final adjusted time. This will show a modal with both time and date, inherited from the clockin/out or scheduled times, if any. Date is shown and editable to account for dealing with adjustments to overnight shifts, and removing any ambiguity from times without dates.

Each ‘OK’ on editing will save/update the shift/timesheet info and reload the current set of data view, with new ‘adjusted’ time updated.

closed periods

May/June of 2021, ‘closed_at’ time period was added, with a ‘close’ button added to time period edit screen. ‘Reopen’ functionality was added as well.

Both of these just change a ‘closed_at’ value state between ‘null’ and whatever the current Carbon time is.

Two events were added: * TimePeriodClosed * TimePeriodReopened

These are triggered during the close/reopen process, but no other behaviour is (yet) tied to these events. They are there to provide a place for other logging, notifications, etc if/when needed.

closed_at flag is passed down to timesheet in the ‘time period’ objects, and is used to display ‘(closed)’ next to time period labels in the pulldown.

July 2021

Earlier pass of related work checks time period closed status, and returns error state to front-end Vue code if a change is made (to worked hours, for example) but the ‘closed period status’ isn’t fully respected across the board in all timesheet screen work yet.

CATS-347 calls for adjustment data to be locked in a closed period.
This takes the selectedTimePeriod.closed_at value, and propagates that to TimeSheet, TimeSheetEntry, PayrollView and AdjustmentRow to set ‘disabled’ flag on various input elements accordingly.

Re: CATS-347 testing - code already exists in service libraries to skip updates for adjustments with shifts in closed periods, and a test exists for that - PayrollAdjustmentServiceTest::testClosedTimePeriodAdjustment1

A vue-component test was initially attempted, to verify ‘disabled’ state, but hit problems around null coalescing and transformations during jest/compile/babel/transform steps.