clock in / out ¶

data ¶

A separate ‘shift_time’ table is added to house info about multiple clock in/out states and related metadata (wiw related data, etc).

This is a one-to-one relation with shift, related on shift_id.

ShiftTime will use hasMetadata trait to allow for storage of ad-hoc metadata.

ShiftTime will have

user_clock_in: timestamp of clock in
user_clock_in_note: text note from user during clock in
user_clock_out: timestamp of clock out
user_clock_out_note: text note from user during clock out
wheniwork_time_id: if shift is related to wiw shift, the related wiw ‘time’ clockin/out record id at wiw API

anticipated needs * submitted_clock_in: timestamp of the actual time user submitted clock in * submitted_clock_out: timestamp of the actual time user submitted clock out * adjusted_clock_in: timestamp of any adjustments made by IV admin * adjusted_clock_out: timestamp of any adjustments made by IV admin * internal_note: text note from iv admin about shift time adjustments

‘submitted’ may be different from the value a user posts. for example, a user may enter in 5:30pm, but it was submitted at 5:15pm (they’re clocking in early) or submitted at 6:15pm (clocked in late by mistake). Tracking these discrepancies is anticipated and accounted for here, just not put in practice yet.

this would be in anticipation of keeping track of time and ‘accepted’ time for timeclock/pay stuff.

new terms ¶

“grace period” is a period where users have X minutes to revert a decision.

config/core.php

    'grace_period' => [
        'shift_take' => env('GRACE_PERIOD_SHIFT_TAKE_MINUTES', 0),
        'shift_create' => env('GRACE_PERIOD_SHIFT_CREATE_MINUTES', 0),
        'shift_end' => env('GRACE_PERIOD_SHIFT_END_MINUTES', 60),
    ]

clock in ¶

request ¶

Request will come from user to clock in.

They will submit a date, and a time, and a note for a given shift.

Currently, the date and time and not editable by the user - this may change in the future.

checks ¶

System will confirm the user is associated with the shift.

System will confirm the shift is able to be clocked in to by checking: * is the shift currently approved for the user? * is the shift not already clocked in? * is the shift within 60 minutes of the shift end time?

Not meeting these criteria mean the shift will not be clocked in.

process ¶

A ‘clock in’ ShiftActivity record will be added to the shift activity list.

Related ShiftTime will be updated with

user_clock_in
user_clock_in_note

values.

events ¶

A ‘ClockIn’ event will be generated - any other code that wishes to listen to a clocked in shift can register code to listen for and process a ClockIn event. A corresponding ClockOut event is triggered during the clock out process.

clock in ¶

request ¶

Request will come from user to clock out.

They will submit a date, and a time, and a note for a given shift.

Currently, the date and time and not editable by the user - this may change in the future.

checks ¶

System will confirm the user is associated with the shift.

System will confirm the shift is able to be clocked out of by checking: * is the shift currently approved for the user? * is the shift already clocked in? * is the shift within 60 minutes of the shift end time?

Not meeting these criteria mean the shift will not be clocked in.

process ¶

A ‘clock out’ ShiftActivity record will be added to the shift activity list.

Related ShiftTime will be updated with

user_clock_out
user_clock_out_note

values.

ShiftService::clockInOutToWIW($shift) is called to send the clock in/out times to whenIWork. If the shift is a WIW shift, a WIW time record will be stored (or updated) with the user_* info from the ShiftTime.

Future: the pushing of ‘adjusted’ times from ShiftTime records may have to happen at some point, and it may call for a separate method call, or overriding this call with an extra flag, to push different values

events ¶

A ‘ClockOut’ event will be triggered.

client side / js ¶

The mobile-oriented ‘vet portal’ code was updated to accomdoate a ‘day of’ view, currently the ‘dashboard’ tab - a default landing view.

Dashboard ¶

For the first pass, this will show a default ‘clock in’ for the next shift on your schedule, provided you are within the 3 hour window before the shift start.

JS ¶

bootstrap/vue was updated to 2.14, providing up to date components and bugfixes, including date and time pickers, which are used in the modals for clock in/out modals.

(currently the pickers are marked as ‘readonly’ until users may be allowed to edit their times).

VetPoralHome.vue is the primary component housing the ‘day of’ view, with ShiftClockIn and ShiftClockOut modals for confirming and taking user notes during in/out steps.

other ¶

After discussion with IV, clock in/out will not support multiple clock in/out actions per shift.

UPDATE June 2020 ¶

The /times API endpoint for WIW does not provide desired behaviour for IV.

The wheniwork service calls were split in to clockin and clockout, modified from earlier API call to /times call which is documented to take the attributes used in the methods.

These was modified to be an explicit call to API /times/clockout call to accomodate the ‘note’ value being used a specific way on WIW side. This is an undocumented feature, which also conflicts with some of the /times documented fields.

That said, it’s unknown as to which of the fields may be effective or not on their end, so we’re leaving them in for now

Ideally, we’re off WIW quickly enough that this is not an ongoing concern.

Internal change - data is sent to WIW for both clock in and clock out separately, ‘on demand’ - earlier version only sent both clockin/out to WIW on clockout.

js updates ¶

time ¶

Clockin/out vue components were updated to update client-side ‘time/date’ every 5 seconds. In short term, the actual submitted time doesn’t matter at all, because final detination is WIW and their service only respects the timestamp/moment the data was submitted to their undocumented /times/clockin endpoints.

Client-choice of time/date is disabled in current version - may be allowed to submit user-supplied times in future.

1/25/2022 ¶

Bug found - cleanup in december exposed that the ‘can clock out’ server side validation was not working correctly. The ‘correction’ caused it to be working, but because it hadn’t worked before, this caused end user problems.

Initial ‘hot patch’ was to just remove the check. Patch being added makes the ‘clock out’ limit configurable in system options, and defaults to empty, allowing anything. I think the initial notion of ‘limit clock out to one hour past shift end’ was possibly too narrow, but conceptually correct. Someone who has not clocked out for days then clocking in may end up causing some potential issues to unravel in timesheet calculations, and IV should probably be aware of these to review manually. Automated text reminders to people may reduce this potentiality to a practical non problem in near future.