Shifts and timesheets - KayanOS Documentation

Shifts describe the planned service window. Timesheets display work-time entries in context: member, assignment, position, shift, date, breaks, total work time, status, and, when selected, a project. Use them together to review operational coverage; do not treat either record as proof of physical presence, a legal timekeeping conclusion, or a payment instruction.

When to use it

Define shifts before assigning staff to a service counter, mobile intake team, or regional centre. Review timesheets when managers need to understand work recorded during a day, week, or month, including approved and unapproved entries. The Syrian Citizen Services Directorate uses a regular day shift for the Damascus Service Counter and may use a split shift for an extended service day. A mobile team can use a different approved configuration without changing the counter’s standard shift.

Configuration

Shift type	Use it for	Required operational attention
Regular	One continuous service range	Define working hours, work days, duration, allowances, and any scheduled breaks. Leave breaks empty when the approved shift has none.
Split	More than one working range in a day	Define non-overlapping working ranges and only the scheduled breaks that fit within a range.
Flexible	A duration-based arrangement	Define a non-zero duration; regular working ranges and breaks are not the controlling model.
Marathon	A duration-based extended arrangement	Define a non-zero duration; use only where the organization has approved this work arrangement.

Regular and split shifts reject equal start/end times and overlapping ranges, including a range that crosses midnight. Breaks are optional. When a shift includes one, it must be valid and fit inside the relevant working range; when it includes none, leave the break list empty instead of entering a dummy zero-length break. The available allowance, work-day, and time-zone fields are operational settings; they do not establish an employment-policy rule.

Shift inheritance and override

For an assignment, KayanOS looks for a shift in this order:

Direct assignment shift.
Direct position shift.
The position’s node, then that node’s parent chain.
The position’s location, then that location’s parent chain.

Use a direct assignment shift only when the member is an approved exception. Otherwise, fix the shift at the correct structural level so future assignments inherit it consistently.

Workflow

Define the shift code, multilingual name, type, work days, duration, time zone, allowances, working ranges, and only the breaks that actually apply.
Validate the ranges before assigning anyone. For an overnight range, make sure the displayed range is intentional and does not overlap another range.
Attach the default shift to the appropriate position, node, or location.
Create or update assignments and review the inherited shift. Record an override only for a real exception.
Open Timesheets and choose a day, week, or month. Filter by node, location, project, approval state, and worked-hours view as needed.
Review a time entry with its member, shift, position, assignment, break data, and optional project before approving it.

Review My Attendance

Open My Attendance in the Time section to review the current member’s calculated month. Move one month at a time. The month list summarizes evaluated buckets, warning flags, recorded and unmatched device punches, and locked days; open a day for the shift timeline, minute totals, policy version, and the rule-by-rule explanation stored with that evaluation. The states have different meanings:

Day state	Meaning	Safe next step
Not calculated	No evaluated attendance row exists yet. The current local day is intentionally not evaluated while punches can still arrive; a missing active policy can also pause evaluation.	Wait until the day closes, then ask an attendance administrator to check the active policy and background processing if it remains absent.
Pre-engine	The figures were preserved from before the current rules engine and do not have a current rule-by-rule trace.	Use the preserved totals as historical evidence; do not invent a modern explanation for them.
Evaluated	The day has bucket totals and a replayable trace under the policy version shown on the page.	Review the punches, totals, policy label, and reasoning together. A short trace can be correct for a rest day.

When consequence bindings, salary, and a complete rate basis exist, the day can show the priced lines derived from those inputs. KayanOS refuses to display a price when an input is missing instead of guessing. Treat a day amount as the policy calculation feeding payroll, not as permission to pay or a replacement for the salary slip. The month page can also show make-up minutes owed, ahead, or settled when ledger entries exist. Every member reviews their own attendance by default. A member with list on member_daily_attendance can use the people switcher to read another member’s month; that view is read-only and an unauthorized member link returns no attendance. Reading another member’s day does not grant correction or payroll authority.

Propose a correction from your own day

On your own day, Fix my day appears only when the attendance-correction service allows you to submit for yourself. Add a missing punch, move its time, or change its direction, choose the factual reason, and send the proposal. Existing device evidence stays identified; a changed punch shows its original time. The proposal enters the same scoped HR correction queue described below and does not change the day until it is approved or self-approved under the assigned verbs. While a proposal is pending, the day shows that status and allows the submitter to withdraw it. A manager who is merely viewing the member through the people switcher never receives this self-service editor. A locked-period warning does not override correct_locked_period; the server remains the authority.

Configure Attendance Policies

Attendance Policies appears in the Time section only for a member with create or update on attendance_policies. Navigation visibility is not a permission grant: policy, version, rule, organization-setting, and activation writes still require their server-enforced entity permissions. If no policy is available, attendance evaluation is paused. Create policy saves a neutral starter as a draft; it does not activate payroll consequences. An existing draft is also not what the engine runs. Review and save the draft, then use the separate Activate action only after approval. Activation archives the prior active version and makes the selected version available to later attendance evaluation. It does not rewrite an approved salary slip; locked-period changes continue through adjustment handling. Use New policy when a different audience needs a separate rule set. KayanOS creates a neutral non-default draft and opens it for configuration. When more than one policy exists, use the Policy selector to confirm which policy you are reading or editing before changing rules, scope, simulation, or activation. Creating or selecting a policy does not change the active policy by itself. In Rules, review the measured families for late arrival, early leave, break overrun, unexplained shortfall, overtime, absence, rest-day work, and holiday work. For each family, bands must cover their range without gaps or overlaps. If a family is empty, choose Add the first band to create one band from zero through the open-ended upper range, then add boundaries to split it. A band records a minute boundary, an outcome bucket, and an optional multiplier; an empty multiplier means forgiveness, not a numeric zero. Conditional rules are visible but read-only in this editor. The policy’s displayed band-math mode controls how a matched band is applied. Use Try a time on late arrival with a representative or selected real shift to inspect the same trace renderer members see. After saving a draft, Simulate replays the previous month and reports changed buckets, affected members, skipped days, and whether conditional rules make the result only a lower bound. A preview or simulation changes no attendance data and is not approval to activate. The Assigned to tab explains the policy scope. The default policy is a pinned catch-all and cannot be narrowed in this editor. On a non-default policy, select people directly or use a node with the intended hierarchy reach, a location, or a position. These selectors and any stored shift or position selectors form a union: matching any one can select the policy. Organizational selectors resolve against current membership when attendance is evaluated, so a later assignment or hierarchy change can change who matches without another policy edit. Save the scope separately, then test direct members and representative hierarchy matches. Policy resolution is part of the day evidence, so verify the policy version shown on representative member days after activation. Set the organization working days per month from 1 to 31 only when payroll has approved that divisor. Hours per day come from the member’s shift; a specific assignment can override either workdays per month or hours per day. Blank or non-positive overrides inherit. If any required rate input is missing, attendance remains unpriced rather than using a guessed rate.

Correct a flagged attendance day

KayanOS checks active assignments with shifts for attendance problems. A blocking flag can mean an unmatched check-in/check-out, a duplicate check-in, an implausibly long pair, or no punches on a scheduled work day without a full-day leave or holiday. A suspicious flag can identify very short recorded work or punches far outside the shift window. A flag is a prompt for human review, not proof of misconduct, absence, or pay treatment. Open Attendance Corrections from the Time section, a warning marker in Timesheets, an attendance notification, or the optional Attendance needing your attention Home tile. The navigation entry appears when the member has at least one scoped submit, approve, or dismiss verb, and the queue is limited to the union of those scopes. It opens on the last 30 days ending yesterday and Needs action, because a still-running day can look incomplete before the final punch arrives. Narrow the queue with searchable department/node, location, team/group, and person filters; use Include historical flags only when older work is required. Reset filters restores the ending-yesterday window, Needs action, no historical flags, and every scope the member may see. For one flagged day:

Open the row and verify the member, local date, plain-language reason, shift window, original device punches, derived gaps, and worked/break/versus-shift totals.
If punches are wrong or missing and you hold submit for that member’s scope, add a punch, move its time, change its direction, or remove it from the proposed day. Dragging the timeline and typing in the punch list update the same draft. The timeline marks worked, gap, and still-broken segments and can offer the likely missing punch at the shift boundary. Removing an original device punch proposes voiding it after approval; KayanOS retains the original and its correction provenance. Use Discard changes to restore the punches as loaded; it deliberately keeps the selected reason and typed justification, so review those separately before submitting.
Choose the factual reason. Other requires a justification. Do not make a speculative change simply to clear the flag.
Use the action KayanOS derives from your verbs. Save correction applies immediately when you can both submit and approve for the member. Send for approval creates a pending proposal when you can submit only. A reviewer with approve sees the submitter, reason, note, exact add/remove/move operations, and proposed day before choosing Approve or Reject. Rejection returns the flag to the needs-action queue.
If the punches are already correct and you hold dismiss, use Actually correct. For a scheduled day with no punches, Confirm absence records that distinct assertion. Either action closes the flag without changing punches; it does not register leave or decide pay.

A gap is derived from the punch sequence and appears as a scheduled break, registered hourly leave, or unpaid break. When the organization owner or an organization-scoped administrator has configured an absence-resolution form, Register leave starts a real form session with the known member, date, and applicable hours offered to matching form variables. The form keeps its own required inputs, access, balance, and approval rules. Starting it does not approve leave or turn the gap into paid time. When every open flag in a deliberately narrowed result is known to be false, a member with dismiss for those exact rows can use Dismiss N flagged days. The button count comes from the filtered rows the server says that member may dismiss. The confirmation requires typing the exact count and then dismisses all currently filtered, eligible open flags—not only the visible first page. Bulk dismissal does not correct punches or create a pay consequence; it asserts that the flags are not real problems, and it cannot be undone in bulk. Never use it merely to clear a backlog. New live flags can notify the affected member, submitted proposals can notify eligible approvers, and decisions can notify the submitter. Delivery still follows notification preferences, channel readiness, and quiet hours. Historical backfill before the organization’s activation date is intentionally silent even though its flags can appear when historical work is included.

Correction permission and safety boundaries

Attendance correction uses four separate scoped verbs: submit, approve, dismiss, and correct_locked_period. An employee may be limited to submitting their own day; a manager may approve for members in their hierarchy; HR may hold a wider approved scope. Seeing Timesheets, a Home count, or a notification does not expand any of those scopes. An approved salary slip locks its month. Without correct_locked_period, the day is read-only for correction. With that exceptional verb, an approved correction is marked retroactive and recomputes attendance, but it never rewrites the approved salary slip; payroll must review the resulting adjustment through its accountable process. KayanOS compares the punch set you reviewed with the current set before applying a proposal. If the day changed meanwhile, reload it and review the fresh data; reloading discards the stale local draft. After approval, recomputation runs through the normal attendance pipeline and anomaly detection checks the day again. Verify the resulting Timesheet state—a correction can be accepted yet the day can reopen if it remains anomalous.

Worked example

The Damascus Service Counter is open Sunday through Thursday from 08:00 to 16:00.

Shift: SHIFT-DAM-DAY — Damascus Counter Day Shift Type: Regular Working range: 08:00–16:00 Break: 12:00–12:30 Position: Intake Adviser Assignment: Rania inherits SHIFT-DAM-DAY through the position Time entry: 3 September, 08:05–16:02, with break and optional link to the intake-modernization project

The manager filters the Timesheets view to Damascus Regional Citizen Services and the selected day. If a time entry needs approval, the manager checks its context first. In the current screen, approving selected members can update all loaded, unapproved entries for those members in the active filtered date range. Narrow the date/filter view before using that action.

Testing

Use temporary shifts and assignments with no live attendance or payroll reliance.

Create one regular test shift with a valid range and no break, and confirm it saves with an empty break list.
Add a valid break to that test shift and confirm it remains inside the working range.
Try an overlapping or equal-time range and confirm the form prevents an invalid save.
Create a temporary position/assignment and confirm inherited shift behavior.
Change only the temporary assignment to an override and confirm the exception is visible.
Create a temporary time entry where permitted, then filter it by date, node/location, and optional project.
Test approval only with records created for the test and a narrow date filter.
In a non-payroll test month, create one missing-punch flag and verify that an employee with submit sees Send for approval, an authorized reviewer sees the exact proposal, and an unrelated member cannot open or act on the day.
Verify the default queue ends yesterday, then narrow it independently by one department/node, location, team, and person. Confirm Reset filters restores the full permitted scope and default dates.
Test Discard changes after moving one synthetic punch and confirm the punch draft returns to its loaded state while the reason/note remain available for review.
Test self-approval, dismissal, and the leave hand-off only with specifically assigned test verbs and a test form. For bulk dismissal, use a tiny controlled filter, read the count before confirming, and verify an out-of-scope/open flag is untouched. Confirm that removing an original punch preserves it as correction history and that an approved proposal recomputes the Timesheet.
As a regular test member, open My Attendance, verify the current month and one historical day, and submit then withdraw one synthetic own-day punch proposal. Confirm a manager’s people-switcher view is read-only.
As a policy administrator in a non-payroll test organization, create a second policy with New policy and confirm the Policy selector keeps its draft separate from the catch-all. In one empty family, use Add the first band, introduce a test boundary, and confirm a gap or overlap cannot be saved. Use Try a time with a test shift.
Assign that draft directly to one test member and through one narrow node/location/position selector. Save the scope, move a second test member into and out of the selected structure, and verify policy resolution follows the current organization structure without narrowing the pinned catch-all.
Save the draft and run its simulation. Record skipped days and any lower-bound warning. Do not activate from simulation results alone.
After an authorized test activation, verify a newly evaluated test day names the expected policy version. Confirm the old active version is no longer selected and that an approved salary slip was not rewritten.

Never use a broad “all members” approval action as a test in a live operational date range.

Troubleshooting

Situation	Check	Resolution
A shift will not save	Ranges, breaks, and duration	Correct an equal/overlapping range or invalid break; for flexible/marathon shifts, provide a non-zero duration.
A shift without a scheduled break will not save	Whether an obsolete required-break rule still applies to the organization’s shift field	Confirm the current shift configuration makes breaks optional; leave the list empty rather than adding fabricated times.
A member has the wrong shift	Inheritance order	Check assignment, position, node hierarchy, and location hierarchy in that order.
A structural shift change has no effect	Assignment override	Confirm whether a direct assignment shift is intentionally overriding the inherited value.
A time entry is not visible	Date, node/location, project, and approval filters	Widen only the relevant filter and confirm the entry’s position/project relation.
More entries changed than expected during approval	Active date/filter view and selected members	Review the loaded entries; the approval action applies to unapproved entries for the selected members in that view.
My Attendance has no days	Selected month, whether the local day has closed, active assignment/shift, active policy, and background processing	Move to a known historical month. If a completed day is still absent, ask the policy/job owner to investigate; do not create a manual day row.
A manager cannot switch to another person	The viewer lacks `list` on `member_daily_attendance` or the member is outside readable scope	Use the viewer’s own page or correct the narrow read role; do not share a member query link as a bypass.
The self-service correction card is absent	The page is showing another member, or the viewer lacks a usable self `submit` path	Use Attendance Corrections with the proper scoped role, or ask the role owner to review self-submit access.
A day has totals but no modern rule explanation	It is marked pre-engine/legacy	Preserve the historical figures and use later evaluated days for policy-trace verification.
A day has no priced lines	Missing active bindings, salary, organization workdays, shift hours, or valid assignment overrides	Complete the approved rate basis and bindings; do not infer a monetary effect from raw minutes.
Attendance Policies is absent	No `create` or `update` verb on `attendance_policies`	Ask the role owner for the narrow administration verb only if policy management is part of the member’s duties.
The expected policy is not in the editor	Only one policy exists, or a different policy is selected	If several policies exist, choose the intended one in Policy. Create a separate draft only for an approved audience; do not alter the catch-all to imitate a missing policy.
A rule family has no editable rows	The selected policy has no bands for that family	Choose Add the first band, then deliberately set its result and add reviewed boundaries; do not activate the neutral open-ended band without checking its consequence.
A member receives the wrong policy	Direct-person, node hierarchy, location, position, or stored shift/position selectors overlap	Review every selector as a union, correct the narrow source, save scope, and verify the member’s evaluated day. Do not freeze a dynamic group by copying a broad list of people.
Policy changes are saved but have no effect	The version is still a draft, no policy is active, or the day has not been recomputed	Review the draft and simulation, activate through the authorized change process, then verify a later/recomputed test day. Do not edit stored day totals directly.
Policy activation or simulation fails	Entity write scope, incomplete/gapped bands, missing draft version, or background-run error	Preserve the draft and error, correct the specific validation/permission issue, and rerun safely; do not broaden the role or activate an unreviewed replacement.
An attendance flag or Home count is missing	The ending-yesterday 30-day/state filters, scope facets, Home layout choice, active assignment/shift, and the viewer’s correction scope	Reset or widen only the relevant filter; check Include historical flags only when needed, then ask the role owner to review the narrow verb scope. Do not grant broad HR access to make one row visible.
Today’s incomplete day is absent from the default queue	The default window intentionally ends yesterday	Extend the To date only for a specific live-day investigation; do not bulk-dismiss an in-progress day’s temporary anomaly.
Dismiss N flagged days is missing or the count is smaller than the queue	The current filters, open/resolved state, and whether the viewer holds `dismiss` for each row	Treat the button count as the authoritative eligible set. Narrow the queue or send the remaining rows to the appropriate scoped reviewer; do not broaden the role.
Punch edits were discarded but the reason/note remains	Discard changes restores only the loaded punch draft	Recheck or change the reason and justification explicitly before the next submit; do not assume they were cleared.
Register leave is missing	Whether the organization owner/admin configured a valid absence-resolution form and the member can start it	Use the approved leave workflow directly or ask the settings owner to repair the form setting; do not record paid leave in the correction note.
The day says the salary period is locked	An approved salary slip exists and the viewer lacks `correct_locked_period`	Stop and send the case to the authorized payroll/HR exception owner. Do not reopen or replace the approved slip as a workaround.
The day changed while editing	Another punch or correction changed the reviewed punch set	Reload the day, compare every punch again, and recreate only the still-valid proposal.
An approved correction still shows a warning	Background recomputation is pending or the corrected punch sequence remains anomalous	Refresh Timesheets and the queue after processing; if the flag reopens, review its new reason rather than dismissing it automatically.

Permissions and data-quality limits

Shifts, work-time entries, own-attendance reading, other-member attendance reading, policy administration, attendance corrections, and payroll exceptions have separate capabilities. A user who can view a position, node, or their own day does not automatically have permission to read another member, edit a policy, approve time entries, correct punches, dismiss a flag, or alter a locked period. Saving a policy draft is reversible review work; activating it is a consequential rules change. Approving a time entry or correction changes operational data; it does not certify attendance, authorize overtime, trigger payment, or establish a legal record. An optional break field does not decide whether employment policy requires a break. Record the approved schedule truthfully, and do not omit a required break merely because KayanOS permits an empty list. Keep notes and project links factual and limited to operational context. Verify corrections through your organization’s approved review process. KayanOS shift and timesheet for a representative service-centre team.

KayanOS shift and timesheet for a representative service-centre team.

Set structural defaults in Nodes and locations.
Assign people and approved exceptions in Groups, positions, and assignments.
Record time away in Holidays and leave.

​When to use it

​Configuration

​Shift inheritance and override

​Workflow

​Review My Attendance

​Propose a correction from your own day

​Configure Attendance Policies

​Correct a flagged attendance day

​Correction permission and safety boundaries

​Worked example

​Testing

​Troubleshooting

​Permissions and data-quality limits

​Related guides