By the end of this chapter you can

• Say what employment records with effective dating keep, and why overwriting job history is a pitfall.
• Explain why punch edits keep the original time and reason, and what FLSA requires.
• Name the seven standards this module is built against and what each one is used for.

What M21 People, time and attendance does

This module owns the people who work at a plant, their jobs and pay, their time clocks, time off, shift schedules, hiring and the export to payroll. It replaces the HR database, time-and-attendance platform, and recruiting tool a business usually pays for separately: ADP Workforce Now, UKG Pro (formerly Kronos), BambooHR, Rippling, Gusto, Paychex, Paycom, Paylocity and Workday are the most common.

What it does not do: payroll calculation, tax withholding and tax filing stay with the payroll provider. Compensation stays restricted to the HR manager role, with field-level access control so a supervisor cannot see another person's pay rate.

The employment record with effective dating

An employee's job and pay change over time: a hire, a promotion, a raise, a transfer, a demotion. The pitfall is overwriting the old job when recording a new one. Effective dating keeps every change as a separate row with effective_from and effective_to dates, so nothing is ever overwritten and the history is complete.

Time clocks and punch edits

A punch is a time-clock entry: in, out, break start, break end, or job change. When a supervisor corrects a punch, a new punch is inserted with source manual_edit. Its punched_at is the corrected time and its original_punched_at is the time first recorded, with edited_by set to the supervisor and edit_reason filled in. When the first value is simply missing, as with a forgotten clock-out, original_punched_at stays empty and the reason says why. The original punch is never changed or deleted.

Why this matters: the Fair Labor Standards Act (29 CFR 516) requires that employers keep accurate records of hours worked. An audit trail of punches, original and corrected, is the proof.

Seven governing standards

References

1. U.S. eCFR: 29 CFR Part 516, records to be kept by employers. https://www.ecfr.gov/current/title-29/part-516
2. U.S. eCFR: 29 CFR Part 778, overtime compensation. https://www.ecfr.gov/current/title-29/part-778
3. U.S. Department of Labor: Fact Sheet #23, overtime pay requirements of the FLSA. https://www.dol.gov/agencies/whd/fact-sheets/23-flsa-overtime
4. California Department of Industrial Relations: overtime FAQ. https://www.dir.ca.gov/dlse/faq_overtime.htm
5. U.S. eCFR: 29 CFR Part 825, the Family and Medical Leave Act. https://www.ecfr.gov/current/title-29/part-825
6. U.S. eCFR: 8 CFR 274a.2, verification of employment eligibility (Form I-9). https://www.ecfr.gov/current/title-8/section-274a.2
7. U.S. Equal Employment Opportunity Commission: EEO-1 data collection. https://www.eeoc.gov/data/eeo-1-data-collection
8. NIST SP 800-122: Guide to protecting the confidentiality of PII. https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-122.pdf

By the end of this chapter you can

• Name the key hr_ tables and say what each one holds.
• Explain effective dating and why a closed assignment stays visible.
• Say how overtime is calculated using federal FLSA and state rules, and which data is restricted.

The 19 tables

The module uses 19 tables to hold employment (hr_employment, hr_position, hr_job_assignment, hr_compensation), time off (hr_time_off_policy, hr_time_off_balance, hr_time_off_request), time punches and rules (hr_time_punch, hr_overtime_rule), timesheets (hr_timesheet, hr_payroll_batch), scheduling (hr_schedule_shift), recruiting (hr_requisition, hr_candidate, hr_application, hr_interview, hr_offer), onboarding (hr_onboarding_task) and performance (hr_review).

The table below is the full definition: every column the module adds to the standard ones (id, tenant_id, created_at, created_by, updated_at, updated_by, row_version, archived_at, ext), with its type and whether it is required (marked req). Types are written as in the specification: text, int, num (a decimal number), money, bool, date, ts (a timestamp with time zone) and json; an arrow means a foreign key to that table; a list after a colon is the allowed values, enforced as check constraints. unique means unique per tenant. hr_schedule_shift.required_skill_ref is a soft link to trn_skill in module M07: the column holds the id and the database does not enforce it. It is what your agent builds from in Session 2.

Effective dating: never overwrite job history

When an employee is promoted, insert a new hr_job_assignment with effective_from set to the promotion date, and close the old assignment by setting effective_to to the promotion date minus one day, so the end date is inclusive. Both rows stay in the database forever, and each new or closed assignment publishes the event hr.job_assignment.changed. The job on any date D is the assignment where effective_from <= D and (effective_to is null or effective_to >= D). For example, a row closed with effective_to 2023-05-31 is still the job on 2023-05-31, and the next row starts on 2023-06-01. A rule written as 'effective_to > D' would return no job at all on the last day of a closed row.

hr_compensation has only effective_from: a pay change is a new row, and the rate in force on a date is the row with the latest effective_from not after that date. Time-off balances work the same way: each change is a new row with its own as_of, and the current balance is the row with the latest as_of.

Overtime calculation

Federal FLSA requires overtime (time-and-a-half, 1.5x) for any hour over 40 in a workweek, a fixed run of seven days that starts at the same day and hour every week. A few states, such as California, add daily overtime: time-and-a-half for any hour over 8 in a day, and double-time (2.0x) for any hour over 12 in a day. Some states, California among them, add a seventh-consecutive-day rule; in California the first 8 hours on that day are paid at 1.5x and any hours beyond 8 at 2x. Store which rule applies in hr_overtime_rule.seventh_day_rule and the multipliers. Overtime applies only to employees whose hr_employment.flsa_status is non_exempt: skip employees whose flsa_status is exempt, because they are not owed overtime, and test that an exempt employee's 48-hour week gives 0 overtime hours.

Each hour is counted once, at the highest rate any rule gives it. Take five 10-hour days (50 hours) under a California-style daily rule: each day has 8 regular hours and 2 overtime hours, which is 40 regular and 10 overtime in the week. The ten hours over 40 in the week are the same ten hours, so the answer is 10 overtime hours, not 20.

The module stores these rules in hr_overtime_rule with jurisdiction, daily_ot_threshold_h, weekly_ot_threshold_h, ot_multiplier (1.5), daily_dt_threshold_h, dt_multiplier (2.0), and seventh_day_rule (true/false).

Restricted data and what is never stored

The Role and Exposure Matrix grants read access to restricted data to the HR manager role only (with one exception for the employee's own leave request). A row-level security rule in the database enforces this: a supervisor running any query that tries to read hr_compensation is refused by the database, not just hidden on a screen.

References

1. HR Open Standards: HR data interchange. https://www.hropenstandards.org/
2. U.S. Department of Labor: Wage and Hour Division compliance assistance. https://www.dol.gov/agencies/whd/compliance-assistance
3. U.S. Department of Labor: Fact Sheet #28, the Family and Medical Leave Act. https://www.dol.gov/agencies/whd/fact-sheets/28-fmla
4. U.S. eCFR: 29 CFR Part 778, overtime compensation. https://www.ecfr.gov/current/title-29/part-778

By the end of this chapter you can

• Explain the clock-in workflow and what sources a punch can come from.
• Say how a timesheet is approved and what checks must pass.
• Describe the payroll export workflow and why reconciliation is required.

Clock-in workflow

An employee clocks in by pressing a button on a kiosk, mobile app, web screen or badge. The system creates an hr_time_punch row with the server's current timestamp (the record time), the punch_type (in, out, break_start, break_end), and the source (kiosk, mobile, web, badge). For a mobile punch it may save the phone's reported location in geo, only if the person allowed it. The system prevents bad states: no 'out' without an 'in' first, no two 'in' punches in a row, and no punch once the timesheet for that period is approved.

When a timesheet is calculated, an 'in' with no 'out' (or an 'out' with no 'in') is written to hr_timesheet.exceptions as a missed-punch exception. The system does not guess; the employee tells the supervisor, who adds a correction. Approval is refused while an exception is open.

Time off and accrual

Each hr_time_off_policy has an accrual method (per_pay_period, per_hour_worked, annual_grant or none), an accrual_rate, a max_balance_hours cap, a carryover_max_hours limit and a waiting_period_days. Nothing accrues before hire_date plus the waiting period, and a balance never goes above the cap. Every change is a new dated hr_time_off_balance row. An employee requests leave, a supervisor or manager approves it (refused if it exceeds the balance), and when the timesheet covering the dates is approved the request becomes taken and the hours are deducted once.

Timesheet approval

The system keeps one timesheet per employee per workweek and recalculates it whenever a punch is added, applying the overtime rules. The employee submits the week from their screen (status submitted), and a supervisor opens the timesheet for their crew and sees the summary (regular_hours, ot_hours, dt_hours, pto_hours) calculated from the punches. The supervisor checks it against their notes or a hand count. If it matches, the supervisor clicks 'approve'. The system sets status to approved, approved_by to the supervisor's person_id, and approved_at to the server timestamp, and publishes the event hr.timesheet.approved. A person cannot approve their own timesheet. To change hours afterwards, the timesheet is reopened (status reopened), which leaves a trace; an exported timesheet cannot be reopened.

Exercise · Punch and approve a timesheet15 minutes

You need:

Build a week of punches with the test fixture from Session 4, approve the timesheet on the platform, and see a missed punch block approval. Only the clock-in route must use the server clock; a fixture run with the database owner login may set punched_at.

1. 1. Insert five in and out punch pairs dated Monday to Friday, eight hours each, using the test fixture.
2. 2. Have the supervisor open the timesheet for that week.
3. 3. Have the supervisor check the summary (regular_hours, ot_hours) against a hand count.
4. 4. With the fixture, add a sixth day (Saturday) with an 'in' and no 'out', and check that hr_timesheet.exceptions lists it and that approval is refused.
5. 5. Have the supervisor add a manual_edit out at 16:00 with a reason, and check the exception clears.
6. 6. Have the supervisor click 'approve'.
7. 7. Verify that hr_timesheet shows status = approved, approved_by is set, and approved_at is set, and that a new punch for that week is refused.

Outcome: A timesheet with five days of eight-hour shifts is calculated to 40 regular hours; once the sixth day's missing out is corrected at 16:00, it shows 48 hours: 40 regular and 8 overtime. A missed punch blocks approval until it is corrected with a reason. The supervisor approves it, and the database shows approval with supervisor id and timestamp.

Scheduling with a qualification check

A published shift (hr_schedule_shift) names the work centre, the shift, the time and, optionally, the skill it needs (required_skill_ref, a soft link to trn_skill in module M07). Publishing is refused when the employee has no current qualification for that skill. A shift can also be left open (status open) until the supervisor assigns someone; shift swaps and open-shift pickup by employees are in the specification but not built in this course.

Payroll export

The payroll processor selects approved timesheets for one or more periods and clicks 'export'. Before exporting, the system checks that every worked hour has a punch behind it (no phantom hours). The export file is CSV in the layout the provider documents (ADP, Gusto, Paychex, Paylocity, Paycom or other), with columns: employee name, employee_no, period, regular_hours, ot_hours, dt_hours, pto_hours. It never carries a pay rate. The system verifies that the sum of hours in the export file equals the sum of the same hours in the timesheets (reconciliation), marks the timesheets exported, stores the file, and publishes hr.payroll_batch.exported.

References

1. U.S. Department of Labor: Fact Sheet #21, recordkeeping requirements under the FLSA. https://www.dol.gov/agencies/whd/fact-sheets/21-flsa-recordkeeping
2. U.S. eCFR: 29 CFR 516.2, records to be kept for employees subject to minimum wage or overtime. https://www.ecfr.gov/current/title-29/section-516.2
3. U.S. Department of Labor: Fact Sheet #23, overtime pay requirements of the FLSA. https://www.dol.gov/agencies/whd/fact-sheets/23-flsa-overtime

By the end of this chapter you can

• Explain why time-off balances are imported as dated opening entries.
• Describe the parallel run comparison and what must reconcile.
• Say how long records are kept, and how the saving is calculated from real invoices.

Import as dated opening entries

Time-off balances are imported as hr_time_off_balance rows with as_of set to the date of the old system's balance report. Before the first pay period, the system generates three reports: (a) employee count by status (pre_hire, active, on_leave, terminated) compared to the old system, (b) time-off policy totals compared to the old system, (c) open requisitions and active candidates compared. Do not proceed to the first pay period until these three reports show matching numbers.

Candidates are personal data and retention-limited: an imported candidate gets consent_at (when the old system recorded it) and retain_until from your written retention rule, and the row is archived once that date has passed. Closed and rejected candidates are not imported unless you are archiving them for history.

Important: never store Social Security, bank account or card numbers. No hr_ table has a column for them, so a check on a column that is not there could never fire. The protection is three locks: the import script refuses a source file with a column named like one of them, a database check refuses digit patterns in the ext column and the free-text fields, and nothing in the module asks for them. NIST SP 800-122 is the guide.

From candidate to hire

A candidate moves through the stages applied, screen, interview, assessment and offer. An hr_interview holds a scorecard and recommendation; an hr_offer holds the rate and moves from draft to accepted. An application cannot move to hired without an accepted offer. On hire the system creates the employment record (status pre_hire), the first job assignment (change_reason hire), the first pay row and a set of onboarding tasks for HR, the manager, IT, safety, training, facilities and the employee, and publishes hr.employment.hired.

The parallel run and reconciliation

For one full pay period, run both the new module and the old system for the same employees. Compare hours only: the headcount, and for each employee regular, overtime, double-time and time-off hours. The payroll provider's own gross-pay report shows the hours it paid; set the hours in your export beside them. This module never calculates pay, so there is no pay amount of its own to compare. The new module should produce the same total hours as the old system within 1%, the tolerance this course uses; set your own with your payroll person. If the numbers differ by more than that, or a difference for one person cannot be explained, do not cut over. Fix the calculation.

Also verify three critical rules: (1) Punch edits keep the original time and reason, (2) Effective dating never overwrites job history, (3) Compensation is invisible to non-HR roles (proven by a field-level RLS test).

Exercise · Import and verify employees20 minutes

You need:

Import employees from the old system and verify the reconciliation reports.

1. 1. Export five employees from the old system with names, hire dates and job titles.
2. 2. Run the import script's first pass, which counts the rows and shows five samples, and check that it refuses a copy of the file with a column named social_security_number.
3. 3. Import the five employees into the new module with the import script.
4. 4. Run the three reconciliation reports: employee count, time-off totals, open jobs.
5. 5. Check that each report's import count matches the export count.
6. 6. Try to store a nine-digit number in an employee's ext column and check that the database refuses it.

Outcome: Five employees are imported with all fields matching the old system. The reconciliation reports show matching counts. The import refuses a forbidden column, and the database refuses a number pattern in ext.

Cutover, record keeping and saving

Once the parallel run reconciles, choose a cutover date. On that date, tell everyone, stop entries in the old system, and tell the team to use the new module. Watch the first day's punches. If something breaks, roll back.

Before cancelling the old tools, settle how long records must be kept. FLSA requires payroll records for at least three years (29 CFR 516.5) and supporting records such as time cards for two (29 CFR 516.6). Your state may require longer, so check it and keep the old export for the longest period that applies. Form I-9 files follow 8 CFR 274a.2.

After cutover, cancel the old tools. The saving is the old annual cost (from your invoices) minus the new annual cost (usually zero). Write the arithmetic so the owner can see where the number comes from.

References

1. U.S. eCFR: 29 CFR 516.5, records to be preserved for 3 years. https://www.ecfr.gov/current/title-29/section-516.5
2. U.S. eCFR: 29 CFR 516.6, records to be preserved for 2 years. https://www.ecfr.gov/current/title-29/section-516.6
3. U.S. Citizenship and Immigration Services: I-9 Central. https://www.uscis.gov/i-9-central

Choose one answer for each question, then submit. You will see the right answer and why for every question.

1. What is effective dating in the employment record?

ARecording job and pay changes with dates, so history is never overwrittenBMarking the date each employee record expires and is removed from the systemCKeeping only the hire date, so later changes overwrite the one current rowDAdding a last-changed date field to every database record in the module

2. The device recorded a clock-out at 12:00, but the person worked until 13:00. A supervisor corrects it. What is stored?

AThe 12:00 row is updated to 13:00, with edited_by and edit_reason filled in on itBA new manual_edit row: punched_at 13:00, original_punched_at 12:00, editor, reasonCA new manual_edit row with original_punched_at 13:00, punched_at 12:00 and a reasonDThe 12:00 punch is deleted and the supervisor adds a new web punch at 13:00

3. Who may see an employee's pay rate in hr_compensation?

AThe payroll processor, since the payroll export needs itBThe employee and their supervisor, on the timesheet screenCHR roles only, enforced by row-level securityDEvery signed-in employee, as long as the screen hides it

4. Time-off balances are imported from the old system. How?

ALeft out; every employee starts at zero on the cutover dateBAs dated opening entries, checked against the old systemCAs current balances, typed in by each employee from memoryDAs a straight copy of the old tool's table, with no check

5. Where are payroll calculation and tax withholding done?

AIn a spreadsheet the supervisor keeps beside the timesheet screenBBy the AI agent, from the approved timesheets each pay periodCWith the payroll provider; this module exports approved hoursDIn this module, from hr_compensation and the approved hours

6. An employee is promoted and moves to a new position. How is the job history kept?

AAdd a note about the promotion to a comments field on the employmentBDelete the old assignment row and add a new one for the new positionCOverwrite the old position on the one assignment row, keeping its datesDAdd a new hr_job_assignment and close the old one with effective_to

7. Your state has a daily overtime rule (for example: any hour over 8 in a day is OT). Where is this rule stored?

AIn hr_overtime_rule, with the jurisdiction and daily_ot_threshold_hBIn the element M21 document, which the timesheet engine reads each weekCIn the database schema only, as a fixed check constraintDIn the payroll provider's settings, applied after export

8. What sensitive data must never be stored in the employment record?

AEmployee names, hire dates and the employee_no from the old systemBSocial Security, bank account and card numbersCWork phone numbers and work email addresses for each employeeDJob titles, departments and the cost centre of each assignment

9. A timesheet is approved and exported to the payroll provider. What must reconcile?

AHours in the file equal hours on the approved timesheetsBNothing; the payroll provider checks the file after it arrivesCOnly the number of employees in the file and on the timesheetsDThe export date, which must equal the last day of the period

10. What stops new punches after a timesheet is approved?

AThe payroll provider rejects them when the batch reaches itBThe supervisor remembers to ignore any punch that comes in lateCThe employee's phone hides the clock-in button for that weekDA database rule; to change hours, reopen the timesheet first

11. A person works five 10-hour days (50 hours) under a California-style daily rule (over 8 hours in a day is 1.5x) and the federal weekly rule. How many overtime hours?

A20 hours: 10 over 8 in a day plus 10 over 40 in the weekB5 hours: only the weekly rule counts, because it is federal lawC0 hours: the daily rule replaces the weekly one in that stateD10 hours: 2 a day, the same hours that are over 40 in the week

12. Which agency enforces the Federal FLSA overtime rule (40 hours per week)?

AThe Internal Revenue Service, through payroll tax filingsBThe Federal Communications CommissionCThe Department of Labor's Wage and Hour DivisionDThe Department of Commerce, which runs the Census Bureau

Submit answers