Time Card/Time Clock Display

The Time Clock’ User Interface is broken up into two areas, the ‘Time Card’ portion and the Time Clock. The Card area is in goldenrod and covers most of the display. The Time Clock is the Punch area at the bottom in green.

Each area has its own help topic.

The Time Card is subdivided into the memo and entry areas.

NOTE: Context-sensitive help: You can also get help by pointing to something and pressing the F1 key.


Card Memo area

This area is a freeform text entry. Use it to make any notes that do not belong in the memo field for a specific time span or are longer than the 80 character limit for those memos.

Some common things to note here:

  • On your last day of each pay period you should confirm the total displayed in the Punch area and make a note something on the order of “My time is 39:48 as shown.” This tells payroll you saw the total and agree with it.
  • Make notes regarding sick leave, vacation or other time that you expect to be paid for in the absence of explicit entries on your time card.
  • Note expenses you need to be repaid for. A note here does NOT replace the need to properly document any such expenses but it will remind bookkeeping to locate the paperwork and helps ensure you get your money.
  • Or generally, note anything that payroll might need to know to get your paycheck processed correctly and on time.

Implementation note: (you can probably stop reading here)

This program tries to model a physical time card and time clock. However, there are subtle differences. The idea of the card memo is to model physically writing notes on the back of a time card. When the pay period is closed out the ‘card’ along with the notes are printed out in the payroll report and archived. In theory, you are given a fresh card at the start of each pay period. In reality, the entries prior to the cutoff date and the memo are moved off to a different file and any entries made after the cutoff are retained.

The only place the metaphor and reality differ is if you put in a card memo in the period of time between the cutoff date and when the final payroll report is generated. Until the old pay period’s records disappear from your card any memo entered will go into the old pay period’s files which may not be what you intended. In reality, this should not be a problem as we normally close out the pay period early Monday morning before most employees arrive.

Time Entry area

This area is the main ‘timecard’. It shows entries, one per line, for each span of time worked. On a typical day there will be two entries, one before lunch and one for the afternoon. However you can have as many entries on a single day as needed. Each day’s entries will be grouped together in alternating colors with the day of the week at the far left.

The times and the memo field are editable, just click on them to put a cursor in them. You are encouraged to use the memo field for noting why edits have been made to time entries, working at a branch you normally aren’t assigned to, etc. Any edit to a time will cause that entry to be marked “UNAPPROVED” until a manager signs off on the change. Be sure to provide sufficient explanation in the memo field to avoid your manager having to get in contact with you, especially near the end of a pay period.

If you edit the date on an entry, as soon as you hit RETURN or TAB the system will re-sort the display, moving the entry to it’s new day. To get a new entry use PUNCH (while off the clock) to add a line then edit as needed. There is NO way to remove an entry.

A detailed explanation of every item in an entry.  Numbers correlate to the image below.

  1. This indicates the day of the week. Along with the alternating colors this helps you see which entries are part of the same day and makes sure you haven’t forgotten to enter a day.
  2. Each line makes up one span of time worked. This is the time you clocked in. Like all date/time notation in this program it is shown in yyyy-mm-dd hh:mm format.
  3. This is when you clocked out for lunch. This example shows a case where someone forgot to clock out for lunch and caught it when they returned.
  4. This is an approval mark. This indicates the time above wasn’t automatically punched and was approved, in this case by user jmorris.
  5. This mark indicates the entry above has not been approved yet. You should make sure the memo field (9) is filled in with an explanation for why you didn’t clock out when you left work and had to manually correct this entry.
  6. This is what you will see when you punch the clock normally.
  7. This mark indicates the entry isn’t completed yet because you are currently clocked in and working.
  8. This displays the time worked for the entry in hours and minutes. Note that the incomplete entry below also displays a time. It is calculated by using the current time in place of the empty clocked out field.
  9. This area is a freeform memo field. While it won’t stop you from typing, the printed reports clip this at about 80 characters so avoid putting too much here; use the card memo field at the top of the timecard for longer remarks. Besides notes about entry errors, use this field to note things like working at a remote location, expenses associated with this work period, etc.

Punch Bar

The Punch Bar represents the time clock in a traditional paper system. It shows the current time and has the “Punch” that stamps that time onto your ‘timecard’ represented by the goldenrod area above it.

Detailed explanation of every item on the Punch Bar.

  1. Help button. Clicking it gets the Top level help for the timeclock display.
  2. Thus number displays the total accumulated time on the current card. If you are currently clocked in it displays the time you would have if you clocked out at the time the card’s display was last refreshed. I.e. after any change the number will update but it won’t if you simply leave the card displayed for several minutes. You shouldn’t leave a card displayed longer than required anyway.
  3. This is the time the clock will ‘punch’ when you click the button (4). When you first display a card it will have the current time prefilled. You can edit the time before you click Punch but see below for the rules.
  4. This is the only control you should use 90% of the time. It ‘punches’ the timeclock, either creating a new line entry if you are coming in or inserting the out time if you are currently on the clock.


Additional rules for editing in/out times

You can edit the time shown beside the punch within fairly wide boundaries. However most edits will mark the punch as “UNAPPROVED” thus requiring a manager to sign off on the change.

The metaphor used is a traditional timecard and timeclock. The goldenrod area represents your timecard and the green area the timeclock with the official ‘company time’ displayed in (3) by default. If you just PUNCH the card it is assumed to be correct and will normally go straight through to payroll. If you forget to clock in or out you would be forced to manually write the time on the card. This typically requires a supervisor to initial the entry.

This separation between machine “Punched” entries and handwritten entries or corrections is also why any entries changed through a manual edit (clicking a time in the main card area) requires management approval.

You can adjust the time backwards by up to five (5) minutes from the time you first displayed your timecard and it will be considered to have been STAMPED. You can adjust the time forward (typically when clocking out) by up to five minutes ahead of the current time regardless of when you launched the program or what time is displayed in (3). This should cover most typical needs.

If you attempt to clock out more than seven (7) hours after you clocked in the entry will be flagged as “UNAPPROVED” due to work rules that normally prohibit an employee from working six (6) hours straight without a lunch break.

Any attempt to create a single entry spanning more than a twenty-four (24) day will be rejected as that is just too improbable. Besides, it would mess up the reports.

Any attempt to enter a time more than thirty (30) days in the past or future will be rejected outright.

When you close the card it will be checked for additional errors and you will be required to correct them before being allowed to save the card. You can’t have two entries that cover some or all of the same time for example. We aren’t going to pay you twice for the same work; whodaya think we are, the gubbermint? 😉

Image of Card Entry
Punch Bar

Management Interface/Who

This page documents the management interface to the time management system. It can also be invoked as a “Who” type application. The only difference between the two modes of operation is that a manager can click on employees to view their timecards while who is view only.

You can press F5 to refresh the display. F1 displays this page in your browser.

Manager Interface 

  1. UNIX Username and full name of employee.
  2. The desk icon shows the employee is currently clocked in.
  3. The lock means the timecard is currently locked. This usually means the employee is currently viewing the card and thus probably clocked in. However, another manager could be viewing the card. You may not view/edit this card until the lock disappears.
  4. The house icon indicates this employee is off the clock. i.e gone to the house. Or lunch.
  5. A Question mark indicates unapproved time entries that need to be cleared up before this employee can be paid for all of their time.

If you are running as a manager, clicking any of the items associated with an employee will open their time card. There are a few differences when viewing a card as a manager. Clicking an unapproved entry will mark it with your username. Making an edit will mark the entry with your username instead of “UNAPPROVED”. Unapproved entries are highlighted to make them easier to spot.


Management Interface

Payroll Report Generator

payroll report generator

Payroll Report GUI

  1. Enter the cutoff time for the pay period here.
  2. Click here to generate a report. By default, it will be a trial close so you can see the list of exceptions and resolve them. Only after generating a report will the Finalize (5) checkbox be enabled.
  3. This button will present a list of saved payroll reports and let you pick one to view or print.
  4. The print button will print whatever is in the report window (6). Until you load a saved report or generate a new one this button will be greyed out as shown in the sample above.
  5. If the finalize button is checked when you click on Generate Report (2) the system will close out the pay period. This involves archiving the current timecards, creating and archiving a set of cards that only contain records prior to the cutoff time and creating a final report and saving that.
  6. Reports you generate or load will appear here. You can’t make changes, only use the scrollbar to view the report or use the Print (4) button to send a copy to the printer.

Locked records

When you generate a report you may get a message about someone’s card being locked. If you are running a trial close you can cancel and the report will have an error message for that one employee. Never cancel on a final report because someone won’t get paid. Track them down and get them to close their card, find the manager who is viewing/editing the card, etc. Doing a “kill” on the server (as root) is preferable to somebody not getting a paycheck.


Of course this program is bugfree and the network can never go down; so this will never occur. But if something DOES manage to go wrong during a final report run the timecards will be in a state of total disarray, with some cards having been cleared of all records prior to the cutoff time and others not.

Do not despair, for even this has been forseen and planned for. So long as you do NOT simply try running the report again that is. Step one is make sure nobody touches their timecard. Use the building wide broadcast feature in the phone system if you need to but stop any modifications. Step two is to call for help.

When you clicked the button to generate a final report a backup copy of all of the timecards was written. So as long as you don’t try generating the failed report again; thus overwriting the good backup with the now mangled records that is. All an admin need do is look in $DATAPATH/backups and unpack that tar file into $DATAPATH/timecards and everything will be exactly as it was the moment you started the report that crashed.

Time Clock Files Manual Access

Day to day operations of the time management system should not require manual intervention in the files. However there are a few cases where knowledge of how the system actually works and where it stores it’s information will be required. So here is detailed documentation on what is kept where and when you might want to manually access it.

The software itself is stored at $BINPATH. On our installation that is /usr/local/share/timeclock. Example .desktop files are also kept here. Other than those icons you should not need to access any of the files in this area unless you know tcl/tk and need to fix a bug or implement a new feature.

All of the program and data files used by the system are owned by the user timecloc and are protected against modification by any other user except for root. Normal access is via sudo, so parts of /etc/sudoers are considered ‘part’ of this system. (Note: local config of sudoers in Debian is now in /etc/sudoers.d/ and the file for the timeclock is /etc/sudoers.d/timeclock. Use of visudo is still recommended but forced writes from another editor are safe in our use case.) Always use visudo to modify this file. Under normal circumstances the only modifications needed will be to the User_Alias entries defining TCMANAGER and TCPAYROLL to add or remove users from those elevated permissions. TCMANAGER defines who has access to the manager interface (i.e. can approve exceptions) and TCPAYROLL defines who can generate payroll reports.

The final area is $DATAPATH, the storage area where the changing data and archived records are kept. On our installation that path is currently /var/spool/timeclock. There are several sub directories within:


Before a final close of a pay period a backup copy of all timecards is created here. If something goes wrong you will need to manually restore this tar file to the timecards directory.


As a pay period is closed, each timecard is split. The cardmemo and any records that begin prior to the cutoff time are placed in a temporary card and any remaining records are returned to the timecard. The last step in closing the pay period is archiving the cards with the old information into a tar file in this directory.


Whenever a pay period is closed a copy of the report is stored here for archival purposes. It is an ordinary text file and can be viewed with ordinary tools such as less, more, view, vi or loaded into a word processor such as OO.o Note that the filename will be coded with the date/time the report was generated, not the cutoff time.


This directory holds the current live timecard records.

New cards are automatically created as needed but the system has no real way to know when an employee is gone for good so manual intervention is needed to stop an ex employee from continuing to appear on the management/who interface and printing a zero hour timecard each pay period. Once the final payroll for an employee has run delete their timecard file from this directory. You will need to be root to do this.

The format of the information inside a timecard is documented in $BINPATH/README. Exercise care when making any use of these files to maintain file locking as an employee could access these files at any time. This package uses the flock system call to simply lock the entire file for either read or write as needed.