HarvestData is a console application which fetches data Harvest and stores it in a file in a format prepared for Custom Widgets in Geckoboard.
HarvestData currently supports the time tracking system Harvest, and, hence the name, it will probably stay that way :-)
HarvestData has been developed by Reload and the source code can be found on GitHub.
Quick reference examples:
./harvestdata compare --date-from="-8 days" --date-to="yesterday" --chart-type=numberstatbudget --output-file=stat1.xml./harvestdata data --date-from="-8 days" --date-to="yesterday" --chart-type=piechart --chart-period=day --output-file=piechart2.js./harvestdata data --date-from="-8 days" --date-to="yesterday" --chart-type=columnspline --output-file=columnspline3.js- Same as 1, just another timespan
- Same as 1, just another timespan
- Same as 1, just another timespan
./harvestdata data --date-from="-5 mondays" --date-to="sunday last week" --chart-type=columnspline --chart-period=week --output-file=columnspline7.js./harvestdata billable --chart-type=geekometer --date-from="last weekday" --date-to="last weekday" --output-file=geekometer8.xml- Same as 8, but using "2 weekdays ago" as date-from and date-to
./harvestdata data --date-from="first day of 6 months ago" --date-to="last day of last month" --chart-type=columnspline --chart-period=month --output-file=columnspline10.js- Same as 2, just another timespan
- Same as 2, just another timespan
- Same as 2, just another timespan
Detailed explanation of the parameters and commands can be found below.
Clone the repository on GitHub.
CURL and PHP 5.3 must be installed (5.2 won't cut it!).
You might need to change the #! path in the "HarvestData" file. Use "which php" in the commandline in order to find the proper path.
HarvestData needs to know where and how to access the systems involved. This configuration is handled by a config.yml file. Copy the provided config.sample.yml and update it with account information. If your configuration file is not located in the root directory you can specify the path to the config file using the --config option.
HarvestData works by looping through all entries made by users (defaulting to employees) and fetching the data for presentation.
A time period can be specified using the --date-from and/or --date-to options - use a date in the YYYYMMDD format, or use "yesterday" or similar PHP-parsable dates (see examples below).
For outputting we have a couple of different parameters.
You can use --chart-type in order to define which kind of chart the data should be outputted as.
This is used in conjunction with --chart-period which is used for grouping the data in the chart. Currently the following values are generally supported:
- day
- week
- month
The filename of the output can be defined as well, use the --output-file parameter for this. Existing files will be overwritten. See examples later on.
You can also use the --days-back option, requiring an integer.
If no dates are set, the system will use todays date and X days back as defined in the config file (that can differ in each Command).
HarvestData will exclude time entries from contractors by default. Change this behaviour by adding the follow parameter:
--exclude-contractors=false or change it in the config file.
--date-to: 'Date from in YYYYMMDD format (or anything php parsable). Date is inclusive. Today is default.'
--date-from: 'Date from in YYYYMMDD format (or anything php parsable). Date is inclusive. DaysBack from config is default.'
--output-file: 'Output filename. Will default to a datetime-stamp.'
--chart-type: 'Chart-type when outputting data. Only usable for FetchBillable and FetchData. See their descriptions for possible values.'
--chart-period: 'Chart period when outputting data. Only usable for FetchBillable and FetchData. E.g.: day, week or month'
--exclude-contractors: 'Exclude contractors hours from the retrieved dataset. Default is true. Boolean value required.'
--config: 'Path to the configuration file. Default is config.yml'
--days-back: 'Overwrite the config setting. Calculate the from-date by X daysback subtracted from to-date. DEPRECATED as of 0.5.'
--harvest-project: 'One or more Harvest projects (id, name or code) separated by , (comma). Use "all" for all projects or "active" for the active ones. DEPRECATED as of 0.5. Might be reintroduced later.'
Run ./harvestdata from the command line to show all available commands.
HarvestData currently supports three use cases:
Fetch entries in Harvest
As of the current version 0.5 it will be outputted as a Geckoboard text-widget.
We use this command for showing the latest 30 Harvest entries from our employees and contractors, displaying them on a status Geckoboard.
./harvestdata entries --exclude-contractors=false --output-file=today.xml
Fetch number of billable hours from Harvest in a specified period
Supported chart-type methods:
- geekometer (built-in Geckoboard widget)
- line (built-in Geckoboard widget)
Fetch all billable data from september 9th 2011:
./harvestdata billable --date-from=20110901 --date-to=20110901
Fetch all billable data from september 9th 2011 and export the data in "geekometer" chart-type format:
./harvestdata billable --date-from=20110901 --date-to=20110901 --chart-type=geekometer
Fetch detailed data
This is probably the most versatile command.
Supported chart-type methods:
- singlecolumn (custom highcharts widget) Show a single column chart, often just billable hours
- columnspline (custom highcharts widget) Same as singlecolumn, but with a budget spline overlay
- stackedcolumn (custom highcharts widget) Shows billable and non-billable bars in a stacked format
- piechart (custom highcharts widget) Well, a piechart with billable vs non-billable data
Fetch data from the last 7 days, output it as the chart "singlecolumn" and output it in the file "singlecolumn.js":
./harvestdata data --date-from="-8 days" --date-to="yesterday" --chart-type=singlecolumn --chart-period=day --output-file=singlecolumn.js
Fetch data from the last 4 whole weeks (monday to sunday) group it by week, draw it as chart "stackedcolumn" and output it as the file "stackedcolumn-week.js"
./harvestdata data --date-from="-5 mondays" --date-to="sunday last week" --chart-type=stackedcolumn --chart-period=week --output-file=stackedcolumn-week.js
And a couple of more examples. Note the chart-period and the clever date values:
./harvestdata data --date-from="first day of 6 months ago" --date-to="last day of last month" --chart-type=stackedcolumn --chart-period=month --output-file=stackedcolumn-sixmonths.js
./harvestdata data --date-from="first day of january" --date-to="last day of last month" --chart-type=singlecolumn --chart-period=month --output-file=year-single.js
Compare billable hours between the assigned period and the same number of days before or the defined budget
Supported chart-type methods:
- numberstat (built-in Geckoboard widget) Shows a number and a percentage (difference between the two provided numbers). The main number is billable hours in the defined period, and the percentage is the difference compared to the previous number of days.
- numberstatbudget (built-in Geckoboard widget) Will display billable hours in the chosen period compared to the defined budget.
Compare billable hours from yesterday with billable hours the previous day (two days ago):
./harvestdata compare --date-from="yesterday" --date-to="yesterday"
At lot of stuff is rather hardcoded right now, quite a bit of the classes are ripe for refactoring. As it works for our usecases it might take a while before we fix this stuff.
Also, take a look at docs/todo.txt and docs/test.txt