Overview | User's Manual | Change History
Time Reporter allows you to record time spent on tasks in terms of start and stop times in a simple text format, then calculates the time worked on each task for each day and each reporting period.
Time Reporter requires the Java Runtime Environment (JRE) version 5.0+ to be installed.
Time Reporter is copyright © 2005-2009 by Basil Vandegriend. The software is licensed for use under the terms of the GNU General Public License (GPL) version 3.0 or later.
The software is provided for use as-is, and is not warranted to be defect-free or to meet your requirements. In particular, the algorithms used to calculate time spent may conflict with the reporting requirements of your organization. If in doubt, inspect the source code (which is provided as part of the release).
The latest version of Time Reporter can be downloaded from the Software page of the site Basil Vandegriend: Professional Software Development.
Feedback concerning this software is appreciated, and can be provided on the Software Feedback page. I would appreciate hearing if you find the software useful and make use of it regularly.
Time Reporter requires two inputs: a task definition file and one or more time sheet entry files (extension of .ts). The software produces a report file for each time sheet entry file named the same as the time sheet entry file with '-Report' appended to the filename, and with a .txt extension. This report contains the time spent on each task per day plus a summary containing the time spent on each task for the entire period contained within the time sheet entry file. Typically a time sheet entry file contains a week's worth of entries, so the summary is for the entire week.
When producing the report, the time reporter calculates the time spent in total each day, and rounds it to the nearest 15 minutes (0.25 hours) (+5 to -9 minutes rounding). This rounded time is called official time because it is what is reported. The rounding error (actual time - official time) is included in the report. The time reporter then calculates the time spent on each task per day, rounding the total for each task to the nearest 15 minutes and ensuring that the task totals will add up to the total for the day.
Time Reporter supports defining three categories of tasks: base tasks, aliases, and rollup tasks. Base tasks are the regular tasks for which time is reported against in time sheet entry files and for which time is reported in the report files. An alias is an alternate label for a corresponding base task that can be used to report time in the time sheet entry files. Aliases are typically short abbreviations of the full task name to make it easier when recording time spent. Rollup tasks, by constrast, cannot have time entered against them. Rollup tasks are used only for aggregate reporting for the entire time period. Each rollup task belongs to a rollup group and has one or more tasks (base or rollup) that are aggregated into it. In the report, a separate section is created for each rollup group to show the aggregate totals of time recorded for each rollup task in the group. Rollup tasks can be defined in multiple levels, in either a strict hierarchy or parallel hierarchy. This is useful in a matrixed organization: one rollup group can be by project and identify the work done per project. Another rollup group can be by department and identify work done per department. A third rollup group could measure overhead activities (i.e. administrative, company meetings) versus value-add activities.
The example directory contains the following example files:
The default behavior of time reporter is to process all files in the current directory with an extension of .ts as time sheet entry files, using for task definitions the file in the current directory called TaskDefinitions.txt. The easiest way to get started is to copy the example directory to a location of your choice and then modify the timereporter.cmd file to point to the TimeReporter.jar file provided in the release. Running the time reporter then just requires executing the timereporter.cmd script.
Time Reporter accepts one command-line argument, which is the name of a time sheet entry file, or the name of a directory which will be scanned for time sheet entry files with an extension of .ts
A sample time sheet entry file is listed below:
November 1, 2005 9:18am foo.fix-bugs 9:22am foo.new-gui # some comment 10:30am - # coffee break - stop tracking time 11:00am foo.fix-bugs 12:00pm - # lunch 12:30pm foo.fix-bugs 1:02pm bar.requirements 5:00pm - November 2, 2005 +10m foo.fix-bugs # my comment 9:16am bar.requirements 1:20pm bar.design 3:20pm sick 5:00pm - +1h on-call
For each day, you specify the time you start a task and the name of the task. To start a new task, you just specify the start time and the new task, and the reporter will automatically end the old task on the previous minute. To stop tracking time (i.e. at the end of the day or for a lunch break), just enter a dash (-) for the task. Comments (prefixed by #) are allowed either at the end of a line, or on its own line. Blank lines are ignored.
The format of a time sheet entry file is as follows:
File = {DayEntry}+
DayEntry = {DateLine} {TimeRecord}+
DateLine = {Month Day, Year}
TimeRecord = {TimeAdjustmentLine} | {TimeClockSet}
TimeAdjustmentLine = (+|-){MinuteAdjustment}|{HourAdjustment} {TaskName}
MinuteAdjustment = {WholeNumber}'m'
HourAdjustment = {PositiveDecimalNumber}'h'
TimeClockSet = {TimeClockEntryLine}+ {TimeClockEndLine}
TimeClockEntryLine = {Time} {TaskName}
TimeClockEndLine = {Time} '-'
Time = {HH:MM(am || pm)}
TaskName = any text without whitespace.
A sample task definitions file is listed below:
# --- General definitions with explanatory comments --- # define alias vacation -> Admin/Vacation # define task on its own sick # define alias to task to rollup group. on-call -> Zot/Support/On-Call -> Department_Zot [Departments] # --- Project definitions showing rollup groups --- # Project Foo Definitions foo.new-gui -> Foo/Task_NewGUI -> Project_Foo [Projects] foo.fix-bugs -> Foo/Task_FixBugs -> Project_Foo [Projects] Project_Foo [Projects] -> Department_Zot [Departments] # Project Bar Definitions bar.requirements -> Bar/Requirements -> Project_Bar [Projects] bar.design -> Bar/Design -> Project_Bar [Projects] Project_Bar [Projects] -> Department_Zot [Departments]
Each line of the task definitions file can either be blank, a comment starting with '#',
or a line in the following format:
({AliasName} ' -> ')? {TaskName} (' ['{RollupGroupName}']')? (' -> ' {TaskName} ' ['{RollupGroupName}']')*
Where
The following table lists the typical forms of task definition lines:
| Example Line | Description |
|---|---|
| Task | Define a base task. |
| Alias -> Task | Define an alias for a base task. |
| Task -> Rollup-Task [Rollup-Group] | Define a task rolling up to a rollup task. |
| Rollup-Task1 [Rollup-Group1] -> Rollup-Task2 [Rollup-Group2] | Define a rollup task rolling up to another rollup task. |
Additional validation rules enforced for task definitions:
A sample time sheet report file is listed below, based on the two sample files listed above:
---Report for timesheet 'Nov1-Nov5-2005.ts'---
Legend: each line for a task consists of the following:
[Task Name] [Official Time] [Entered Time - Official Time]
---Daily Reports---
---Tuesday, Nov 01, 2005---
Bar/Requirements 4.00 h (-2 min)
Foo/Task_FixBugs 1.50 h (+6 min)
Foo/Task_NewGUI 1.25 h (-7 min)
Total: 6.75 h (-3 min)
---Wednesday, Nov 02, 2005---
Bar/Design 2.00 h (0 min)
Bar/Requirements 4.00 h (+4 min)
Foo/Task_FixBugs 0.25 h (-5 min)
Zot/Support/On-Call 1.00 h (0 min)
sick 1.75 h (-5 min)
Total: 9.00 h (-6 min)
---Period Reports---
---Base Tasks---
Bar/Design 2.00 h (0 min)
Bar/Requirements 8.00 h (+2 min)
Foo/Task_FixBugs 1.75 h (+1 min)
Foo/Task_NewGUI 1.25 h (-7 min)
Zot/Support/On-Call 1.00 h (0 min)
sick 1.75 h (-5 min)
Total: 15.75 h (-9 min)
---"Departments" Rollup Group---
Department_Zot 14.00 h (-4 min)
Unallocated: 1.75 h (-5 min)
---"Projects" Rollup Group---
Project_Bar 10.00 h (+2 min)
Project_Foo 3.00 h (-6 min)
Unallocated: 2.75 h (-5 min)
---End of Report---